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Preface 


ProDOS™ is Apple's Professional Disk Operating System. A disk 
operating.system is a computer program that serves as a 
housekeeper for the information stored on disks. It allows you to 
place information on disks, rearrange the information that is 
already on the disks, and retrieve information from the disks. 
ProDOS lets you organize and use the information stored on all 
Apple li disks made by Apple Computer, Inc. 


The Parts of ProDOS 


The ProDOS software, or programs, comes on two disks. The first 
disk, labeled ProDOS User's Disk, contains programs that let you 
arrange information on a disk and move information from one disk 
to another. The programs on the User's Disk are explained in the 

ProDOS User's Manual. 


The second disk, labeled ProDOS BASIC Programming Examples, 
holds the program that lets you run other programs, arrange 
information that is already on the disk, and write your own BASIC 
programs that use the disks to store information. This manual 
explains the program on the Examples disk. 


The ProDOS Technical Reference Manual explains what makes 
ProDOS tick. An experienced programmer can use this 
information to write machine-language programs that use 
ProDOS. 


By the Way: The catalog of your Examples disk may show dates and 
times that are not the same as those pictured in this manual. Don't 
worry—it is just to show you what these catalogs look like. 


The Parts of ProDOS 
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Requirements for Using ProDOS 


To use ProDOS, you must have an Apple ۱۱ with at least 64K of 
Random Access Memory (RAM), and with Applesoft in Read Only 
Memory (ROM). If you have a standard Apple Il with Integer BASIC, 
you must replace the Integer BASIC ROM with an Applesoft ROM. 
You must also have at least one Disk II drive; in addition, you can 
have any other combination of disk drives. 


By the Way: In this manual, the name Apple // implies the Apple ۱۱ Plus 
and the Appie !le. Because ProDOS does not support Integer BASIC, 
ProDOS will not work with BASIC on a standard Apple Il. 


Before using this manual, you should be familiar with your Apple il, 
and with the use of Applesoft BASIC. You should also work your 
way through the ۸۵0/9501 Tutorial before you read this manual. If 
you have never used files that are grouped into directories, read 
the ProDOS User's Manual chapter on files, filenames, and 
pathnames. 


Remember: Keep the (CAPS LOCK)key depressed when you are typing 
any of the ProDOS commands; they must be in uppercase letters. If you 
type them in towercase, you will receive a SYNTA» ERROR message. 


if you are experienced with DOS, the predecessor to ProDOS, read 
Chapters 1 and 2 of this manual and then skip to the appendix that 
describes the differences between DOS and ProDOS. 


This Manual’s Organization 


This manual is organized to be useful to as many people as 
possible. Each chapter begins with a section describing the topics 
it covers. If a chapter introduces new ProDOS commands, it also 
has a section called ‘This Chapter's Commands.” Read this 
section carefully; you can use its command summary to find 
commands with which you are unfamiliar. 


Notice that most of the command descriptions have three 
sections. The first section tells you why you would want to use the 
command, shows its form, or syntax, and gives a brief example. 
The second section, “The Options,” gives a precise definition of 
the different abilities of the command. The third section, ‘‘For 
Example,” is a hands-on example of the command. If you learn 
best by doing, try these examples. 
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Here is a quick summary of the chapters and appendixes in this 
manual: 


Chapter 1: 


Chapter 2: 


Chapter 3: 


Chapter 4: 


Chapter 5: 


Chapter 6: 


Chapter 7: 


Chapter 8: 


Chapter 9: 


Appendix A: 
Appendix B: 
Appendix C: 


Appendix D: 


What you should know before using ProDOS. 


What files are and how they are named. What 
ProDOS commands are and how they are structured. 


How to keep track of and manipulate the files on a 
disk. 


How to use programs that are stored on a disk. 


How to write BASIC programs that use ProDOS 
commands. 


How to write BASIC programs that use sequential 
text files. 


How to write BASIC programs that use random- 
access text files. 


How to make files control the operation of your Apple 
computer. 


How to use binary programs and files, and the 
Monitor. How to use a clock/calendar card. 


A summary of ProDOS. 
The ditferences between DOS and ProDOS. 
Error messages. 


Extra programs. 
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Introduction 


Before You Start 


This manual assumes that you already have some experience 
using your Apple ۱۱۰ You should be familiar with the App/esort 
Tutorial and at least Chapter 2 of the ProDOS User’s Manual. 


As you read this manual, you should have in front of you: 
e An assembied Apple II with at least one disk drive 
e The ProDOS User's Manual 


e The disks labeled ProDOS User's Disk and ProDOS BASIC 
Programming Examples, and one blank disk 


è The Applesoft Tutorial (optional). 


Make a Spare Copy of Examples Disk 


While you learn to work with ProDOS, you are asked to do many 
things with your Examples disk. Because the Examples disk that 
comes with your ProDOS package is write-protected—that is, it 
does not have a write-enable notch—you cannot do one very 
important thing to this disk: you can't write information on it. 


Following the instructions in the section on backing up disks in the 
ProDOS User's Manual, transfer a copy of the information from the 
original Examples disk to your blank disk, naming the new disk 
/EXAMPLES . (This is the form that ProDOS recognizes—with a 
slash before the name. You can use uppercase or lowercase letters 
when you name a disk.) Write your name and /EXAMPLES on the 
disk label; this is your personal copy of ProDOS. Now put the 
original in a safe place; someday you may want to copy it again. 


By the Way: Even if someone else has already made a copy of 
/EXAMPLES, it is best to make one of your own. Some of the examples 
in this manual ask you to change the files on the disk; if someone has 
already done these examples, the disk will not be in its original form. 


Make a Spare Copy of Examples Disk 
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Starting ProDOS BASIC 


Place your copy of /EXAMPLES into drive 1 and close the drive 
door. If your Apple 1۱ is off, reach your left hand around to the back 
of the case and turn it on. If your Apple II is already on, reach 
around the back, turn it off, then on again. The display fills up with 
information that looks something like Figure 1-1. 


Figure 1-1. The ProDOS Title 


Screen 
APPLE iE 
FROOOS 1.8 L-SEP-83 
~QOPYRIGHT APPLE COMPUTER, EMC., 1:93 کڈ‎ i 

This display tells you that ProDOS was just placed in memory. Any 
disk that contains a ProDOS program shows this display when it 
starts up. 
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Figure 1-2. The ProDOS Title 
Screen 


What it Tells You 
The startup disk name. 
The type of Apple li. 


The amount of RAM in 
your Appie Il. 


Applesoft BASIC is in 
Read Only Memory. 


The contents of each 
of your Apple II's stots. 





After a few moments more, you see a display that looks something 
like Figure 1-2. Its exact appearance depends on the type of 
Apple ۱۱ system you are using, and the identity of the peripheral 
cards that are connected to your system. 
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you that the ProDOS program was brought into memory from the 
disk named /EXAMPLES. This display also describes the setup of 
your system: how much memory it has, which versions of BASIC 
you can use, and the type of peripheral card installed in each of 
your Apple ۶'ا|‎ peripheral connector slots. 


By the Way: ProDOS BASIC requires at least 64K of memory. An 
Apple lie always has 64K. Any Apple Ii must have 48K of RAM and a 
Language Card to be able to use ProDOS. 


Starting ProDOS BASIC 
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A complete explanation of what 
happens when you start ProDOS is 
given in Chapter 5, "Programming 
With ProDOS." 








The Startup Process 


When you turn your Apple II on, it tries to read information from 
drive 1 of the disk controller card in the highest numbered slot 
(usuaily slot 6) inside your Apple II. If the disk is a ProDOS startup 
disk, the ProDOS program is brought into memory. You see the 
two displays of information described above, followed by the 
BASIC prompt: 


^" 
=i 


When you type a few lines of BASIC, you see that your Apple II 
behaves just as it did without ProDOS or the disk drive—or so it 
appears. The startup process actually added the ProDOS 
commands to the BASIC commands to which you are accustomed. 
There are now 23 new commands that you can type in, and several 
of the old commands have been enhanced. 





Warning 

Even though the ProDOS commands look like BASIC commands (as you 
will see), they do not always follow the same rules. For example, multiple 
ProDOS commands, separated by colons, cannot be put on one line. 
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Other Ways to Start ProDOS BASIC 


On an Apple lle, you can always start the system by pressing the 


three keys—(G), (CONTROL), and (RESET)—-all at the same time, and 
then releasing them. On any Apple ۱۱ computer, you can start the 
system by turning the computer off and then on again. 


When you see one of the prompts (= or +), you can usually restart 
the program on the disk in drive 1, siot 6, using the command 


mp dk m 
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If you see the monitor prompt (+), and ٣۶۶ ۶ doesn't work, try 
typing 


(6 )(CoNnTROL)-(P) 


If your disk controller card is installed in another siot, replace 6 
with the siot's number. 


These commands are explained later. For now, remember that 
using them is a good way to start over if things seem to be 
hopelessly confused. Beware, however -—these commands make 
everything that is in memory disappear. 


The HELP Command 


If you are using ProDOS and can't quite remember the exact form 
of a command, you can add the HELP command by typing 


ا إا 
سا E‏ 


-— we stat hie | از‎ 
1" سط 4 ۶۴ 5 ۲ سا‎ i-— ". 


while the Examples disk is in a drive. You need to type this 
command only once. The HELP command remains in memory until 
you turn off your computer or use another program (such as the 
ProDOS Filer). 


After you do this, you can get help with any ProDOS command by 
simply typing 


HELF command 


while the Examples disk is in a drive. Replace the word command 
with any one of the ProDOS command words (that you're going to 
learn). !f you just type 


HELF 


you wiil see the list of command words shown in Figure 1-3. 


The HELP Command 





D coo; 


` AERA و‎ iy 
kate rx o AIRE 


Figure 1-3. The HELP Selection 
Screen 


Where Explained 
Explanatory displays. 
See Chapters 1, 2, 9. 


See Chapter 3. 


See Chapter 4. 


See Chapter 5. 


See Chapters 6, 7, 8. 


See Chapter 9. 


What You See 

HELF £a uzer-added command? 

TO use, type: HELF HH CBR بت‎ below? 

Explanatory: HELP. SYHTAR, BINARY, 
FILE 

Using Files CAT, CATALOGS, PREFIX, 
CREATE, RENAME, DELETE, 
LOCK, UNLOCK 

BASIC in Files: - LORD, RUH, SAVE 

Fr ح وت‎ anina : THAIN, STORE. RESTORE, 
PRE. # HUE 

Text in Files: OPEN, CLOSE, WRITE. vi 
EERO, APPEND, POSITION, 3 
FLUSH, ناج‎ 4 

Binary Files: — BLORD, BRUN, BSRVE. | 

A ید‎ A 
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The left column lists the use for each group of commands. The 

column on the right lists words you can enter in place of i, the 


name of the command you want to use. The first group of 
commands is explanatory because the commands HELP HELP, 
HELP SYNTAX, HELP BINARY, and HELP FILE do not give help 
with specific commands; they display explanatory information. 


Each group of commands corresponds to one or more chapters, 
and within each group, the help commands are listed in the order 
they appear in this manual. 


For the HELP command to work, the files named HELP and 
HELPSCREENS must be on the same disk. To get them onto a 
disk other than /EXAMPLES, copy them using the ProDOS Filer. 
This is explained in more detail later. 





For Example 


If your Apple It is turned off, make sure /EXAMPLES is in drive 1; 
then turn on the computer. 


As soon as the prompt character appears on the display, type 


- - EXAMPLE 


-HELP 
ra t اٹ‎ 
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Figure 1-4. The CATALOG Help 
Screen 





When the BASIC prompt returns, type 


and you will see the list of commands shown in Figure 1-3. If you 
want to see a typical help screen, type 


RTH iS 


1 e 


HELF 


and you see the display shown in Figure 1-4. 


Bg CATALOG Clam & Df? 


Show an S8-column directory listing 
2 


0 


5 


Form: CAT Cerd €,2#3 £2,042 


G 
RLOG -BUDGET AJAH 


Example: c 
ALEG. ze, De 


CRT 
CRT 


8 
A 
The first example lists the files in 
the directory -BUDGET.-JAH; the second 
lists files in volume directory S6, Be. 


This command shows the zame items as 
i CRT. In addition, it shows the date .- .. 
' the file was created, the losgirai- ini 
lenath of the file, and some subtupe. 
| information. jov 


` See HELP CAT. 


At the top of the display is the name of the command, CATALOG, 
followed by the message © Imm à De? ;. This message tells you 
that the CATALOG command can be used in immediate mode (as 
a command typed from the keyboard), and in deferred mode (as a 
line in a program). 


Next is a line that describes what the command does; one more 
that shows the form, or syntax, of the command; two lines of 
exampies; and then an explanation of the command syntax. All the 
abbreviations shown in the display will be much clearer after you 
finish Chapter 2. 


All the help screens use this same format with some variations due 


to the requirements of each individual command. 


The HELP Command 





You can remove the HELP command by typing 


HOHELF 
This should be necessary only if you are writing an extremely large 


UMS ProDOSand DOS 


Because there are many programs available that are written using 
DOS, it is important that you understand some of the differences 
between ProDOS and DOS. 


When you start up a ProDOS disk, the ProDOS program is placed 
into memory. The ProDOS program is able to write to and read 
from all disk drives made for Apple Il computers by Apple 
Computer, Inc. 


When you start up a DOS disk, the DOS program is placed into 
memory. The DOS program can write to and read from Disk li 
drives only. 


Appendix B, which describes the The information that ProDOS places on a disk cannot be read by 

differences between ProDOS and DOS, DOS, likewise, the information that DOS places on a disk cannot 

ipsis Het. a program from “be read by ProDOS. However, in some cases you can use the 
program CONVERT on the User’s Disk (/USERS.DISK), described 
in the ProDOS User’s Manual, to convert information from one 
format to the other. 


This means that you can use your existing DOS programs only on a 
DOS-formatted disk unless they can be converted from DOS 
format to ProDOS format. The generai rule is that programs you 
buy cannot be converted, and that programs you write yourself 
can be. ۶ا‎ a program uses only BASIC and DOS commands, it can 
be converted. If it does any tricky PEEKs and POKEs, or if it uses 
machine language at all, then it is likely that it cannot be 
automatically converted. 
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The ProDOS User's Manual explains 
how to format disks. 


See Appendix B for more details on 
DOS and ProDOS. 


Files and Commands 


About This Chapter 


The first part of this chapter is about files. It explains how ProDOS 
arranges files on a disk, how files are named, and the terminology 
used to refer to files. 


The second part of the chapter explains how ProDOS commands 
are structured. These commands let you make use of your files. 


Some of the information in this chapter is explained by example: 
as you read sections entitled ''For Example," try the examples. For 
these exampies to work, ProDOS must be running, as explained in 
Chapter 1, and the Examples disk must be in a drive. 


Disks 


The purpose of ProDOS is to let you use the information on disks. 
It can communicate with all disk drives built by Apple Computer, 
Inc. for Apple It computers. Before ProDOS can use a disk, the 
disk must be prepared for use, or formatted. You can format a 
disk using the ProDOS Filer. 


You'll find it convenient always to have an adequate supply of 
empty ProDOS-formatted disks on hand, and to mark each disk 
so that you know that it is ProDOS-formatted. Disks of other 
formats (Apple ۱۱ Pascal, DOS) cannot be used by ProDOS. 
Apple Ill SOS-formatted disks can be used by ProDOS (although 
the programs on them cannot). 


Disks 
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Figure 2-1. Files in a Directory 
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Files 


ProDOS lets you organize information into units of disk storage 
known as files. Files can contain numbers, phone lists, letters, 
pictures, programs, or any other type of information that your 
Apple Il can use. 


When a fiie is placed on a disk, it is assigned a name and a type. 
When you want access to the information stored in a particular file, 
refer to that file by its name. The file’s type indicates the kind of 
information that the file contains. For example, there are text files, 
program files, and a very important file type: directory files. 





Directory Files 


A directory file is just like any other file, but instead of containing a 
program or text, it contains a list of other files and their locations 
on the disk. 


DIRECTORY 


FILE1 FILE2 FILES FILE4 


The directory shown in Figure 2-1 contains four files: FILE t, FILE2, 
FILES, and FILE4. Each of these files can be of any file type; thus 

all, some, or none of them could be directory files. You can use up 
to 64 levels of directories on a disk; however, more than five or six 
levels of directories are difficult to use. 
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A volume directory is the main 
directory file for the entire disk. 


CAT is the short version of CATALOG. 


Volume Directory Files 


When you format a disk using the ProDOS Filer, a special type of 
directory file is automatically placed on the disk. It is called a 
volume directory, and it is the main directory file for the entire 
disk. 


A ProDOS volume directory 
٭‎ is on every ProDOS-formatted disk. 


* has a name, assigned when you format the disk. This name, 
being associated with the entire contents of the disk, is also the 
disk's name. You should place it on the disk’s label. 


e can contain up to 51 files. 


© is the only file that you cannot create using the CREATE 
command (or the ProDOS Filer command, MAKE DIRECTORY). 


is the only file that you cannot remove from a disk (although you‏ ٭ 
can remove all the files in it). It is also the only file that you‏ 
cannot protect using the LOCK command.‏ 


if you have an Apple tle with an Extended 80-Column Text Card, 
ProDOS places a volurne directory file in the alternate 64K of RAM 
on the card. This volume is named /RAM and it can be used just 
like a small disk. Unlike a disk, however, the information in /RAM 
disappears when you turn off your computer. You should use this 
volume only for temporary storage of information. An example of 
the use of /RAM is given in the following section. 


For Example 


To see the contents of the volume directory of the Examples 
master disk, type the ProDOS command 


CAT EXAMPLE 
1 tot 4 ا ابو‎ t0 ۶ ہے سا‎ 


£11 


and the display shown in Figure 2-2 appears. 


By the Way: Your disk catalog may show dates and times that are not 
the same as those pictured in this manual. Don't worry—they are just 
to show you what these catalogs look like. 


Files 








a “EXAMPLES 


HAME TYPE FLOCKS MOCIFIED 

Figure 2-2. The Main Files on 

/EXAMPLES PROOGOS 55 25 L-OSEP-S53 
8۳5۱0۰ SYSTEM 5:55 ei lI*5EM-2535 
STARTUP BRAS "d 1 ۳ 3 
HELP SIH t i-5EF-23 
۲۶۱۲۳ ۵ THT 53 1-5 جع‎ 5 
DIRECTORY DIR L 11-SEP-83 
PRACTICE DIR 1 11-SEP-83 
PROGRAMS DIR 3 t-SEP-33 
DATA DIR 1 t-5EP-33 
EXTRAS DIR 3 L-SEP-33 
POSTRGE.ERTES EAS 3 L~SEF-—-3 3 
RENUMBER BRS 1-5 5س ماع‎ 
BLOCKS FREE: 12 BLOCKS USED: t73 , 





Some of these files are directory files: they contain the names and 
locations. of other files on the disk. You can recognize a directory 
file by the abbreviation C1 & to the right of its filename in the 
catalog. 


If you have an Apple ile with an Extended 80-Column Text Card, 
type the ProDOS command 


CAT «RAM 


ProDOS displays information similar to that shown above, but with 
no filenames listed. /RAM is empty. 
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Filenames 


Several ProDOS commands cause files to be created; each 
requires that you assign the file a filename. 


A ProDOS filename 


is composed of up to fifteen characters. The first must be a 
letter; the rest can be any combination of uppercase or 
lowercase letters (A-Z), digits (0-9), and periods (.). Lowercase 
letters are automatically converted to uppercase, thus A and a 
are equivalent. 


must be unique within its directory. There can be files by the 
same name in different directories. 


Some Legal Filenames 


Here are a few legal filenames (assuming there aren't already files 
of the same name in the same directory). 





A.LONG.FILENAME longest possible name 
Z shortest possible name 
A.1DERFUL.NAME has letters, number, and periods 





Note: Although you can't use spaces in filenames, you can use periods 
to separate words within a filename. 
Some illegal Filenames 


Here are some illegal filenames and the reasons you can't use 
them. 





3.BLIND.MICE begins with a number 
.PRINTER begins with a period 
SPACE RACE contains a space 
BOOP,BETTY contains a comma 


PEANUT.BUTTER.AND.PICKLES too many characters 





= menm 
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Figure 2-3. The Structure of a 5 
Pathname 


A partial pathname is a file's pathname 
with the prefix removed from the front 
of it. 


Ec 
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Pathnames 


To find a file, ProDOS must know the path (from the disk's volume 
directory to the file) that it must follow to get to the file. The entire 
path, from the volume directory to the file, is called the file's 
pathname. For example, the pathname of a file STAND in a 
directory LAST in the volume directory CUSTER is 
/CUSTER/LAST/STANO . 


A ProDOS pathname 
e is a series of filenames, preceded and separated by slashes 


e has a volume directory filename as its first element 


€ is no more than 64 characters long, including slashes. 


Figure 2-3 represents the structure of a pathname. 


AW FILENAME 


Figure 2-4 displays the directory structure of a disk containing files - 
that document part of the Indo-European family of languages. 
Below it are a few of the many valid pathnames within this 

directory structure. 


in this example, INDO.EUROPEAN is the name of the disk 
containing these files and also the name of the disk's volume 
directory. 





The Prefix and Partial Pathnames 


It is very time-consuming to type in an entire pathname every time 
you use a file. By setting the prefix, a pathname that indicates a 
directory file, you can refer to files in that directory, or to files that 
can be reached through that directory, by using their partial 
pathnames. 
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Figure 2-4. A Sample Directory 
Structure 


BALTO.SLAVIC 


\ 


BALTIC SLAVIC 


A Directory Structure 


INDO.EUROPEAN 


GERMANIC CELTIC ITALIC HELLENIC 
GOIDELIC BRYTHONIC GREEK 





NORTH.GERMANIC WEST.GERMANIC EAST.GERMANIC 


Tabie 2-1. The Prefix and Pathnames 


LATINO.FALISCAN OSCO.UMBRIAN 


And Some Pathnames Within It 


/INDO.EUROPEAN/HELLENIC/GREEK 
/INDO.EUROPEAN/GERMANIC/WEST.GERMANIC 
/INDO.EUROPEAN/ITALIC 
/INDO.EUROPEAN/BALTO.SLAVIC/BALTIC 


Table 2-1 shows the relationship among pathname, prefix, and 
partial pathname. 


Current Prefix Is You Should Type 


You Want ProDOS to Find 


/CAROL/GHOSTS/XMAS.PAST /CAROL/ GHOSTS/XMAS.PAST 
/CAROL/GHOSTS/XMAS.FUTURE /CAROL/GHOSTS/ XMAS.FUTURE 
/MY.DISK/GAMES /YOUR.DISK? /MY.DISK/GAMES 


a ———— a —ÓÀ—€ € À ITI للم‎ 


In the third column of Table 2-1. GHOSTS/XMAS.PAST and 
XMAS.FUTURE are both partial pathnames; a full pathname is 
formed by adding the current prefix. In the third example you want 
to use /MY.DISK/, but the prefix is set to /YOUR.DISK/. In cases 
like this, you must use the file's full pathname (or change the value 
of the prefix). 


Make sure you understand the examples in Table 2-1. Once you 
do, you will never have trouble with pathnames, partial pathnames, 
or prefixes. 


Files 
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A 20005 partial pathname 

€ is a filename, or a series of filenames separated by slashes 

is a pathname minus the current prefix‏ ٭ 

€ is no more than 64 characters long, including slashes. 

You can use the PREFIX command to set the prefix. Follow this 
command by the pathname of a directory. Thus, before referring to 


several files that are in the /EXAMPLES/CATALOG directory, you 
can use the command 


rm 


rere. 
mi 
k 


FREI 


I f 


uURMELES 


For Example 


To set the prefix to the name of the directory /EXAMPLES/CATALOG 
use the command 


Now look at the contents of the CATALOG directory with the 
command 


T 
iii 


Without any options, you can use the CAT or CATALOG command -~ 
to display the contents of the prefix directory. Now examine the 
contents of the directory /EXAMPLES/CATALOG/DIRECTORY by 
typing the command 


in two commands, you saved 28 keystrokes! 


The General Form of ProDOS Commands 


This manual describes all the possible forms of each ProDOS 
command by presenting a one-line description of the command. 
This one-line description is called the command's general form, or 
syntax, and it looks something like this: 





command [pn] [,S4] [,Dz] 
The word command represents any of the ProDOS commands. 


The expressions [pn], [,S#], and [,D&] are the command's options. 
There are many options other than these three. 
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The three options shown above are called the pathname, slot, and 
drive options, respectively; together they determine the name and 
location of the file to be accessed. You can specify a file on any of 
your disks using only the pathname option. The slot and drive 
options give you additional control in accessing files. 


Here is a specific instance of the CATALOG command that uses 
the [pn], [,Sz], and [,D#] options: 


This command tells ProDOS to display the files contained in the 
BOOKS directory (in this case pn is replaced by a partial 
pathname), which is in the volume directory of the disk in slot 6, 
drive 1. 


Note the use of commas in the above example. Commas separate 
the options; you can put spaces before or after the commas if you 
wish. 


Options 


Sometimes an option is shown with brackets around it, sometimes 
not. If an option does not have square brackets around it, you 
must use that option each time you use the command, and you 
must use it in the order shown by the command's syntax. An 
option that has square brackets around it may be included or 
omitted, depending on what you want the command to do. 
Bracketed options can be used in any order. 





Warning 
When you use an option, never type in the square brackets; they are onty 
there to tell you that the option is not required. 





The characters within the brackets do three things: the comma 
separates an option from its predecessor, the capital letter 
identifies which option you are using, and whatever is after the 
capital letter (usually +) stands for the value you can give that 
option. 


The letters pn should be replaced by a pathname or partial 
pathname, as explained below, and # should be replaced by an 
integer. The value of # can be a decimal integer or a hexadecimal 
integer. 





سے دس میاه کس ت سا ند سد as o‏ 





By the Way: An additional notation is used later in the manual. Two 
options separated by a vertical bar, ! , are alternates. Use one or the 
other, not both. You can read a bar as the English word or. 





Hexadecimal Notation 


You are never required to use hexadecimal numbers. The integer 
in an option, represented by #, can be expressed in hexadecimal 
notation by preceding the hexadecimal digits with a dollar sign. 
For example, the decimal integer 254 can be expressed in 
hexadecimal notation as $FE. 





The Pathname Option—[pn] 


[pn] This option indicates to ProDOS the name of the file that you 
want to use. You can replace pn with a pathname or a partial 
pathname. 


If you use a pathname, ProDOS looks for the file with that 
pathname. 


If you use a partial pathname without the [,S 2] and [,D#] options, 
ProDOS tooks for the file having the pathname formed by the 
partial pathname added to the prefix. If the prefix is empty, the 
name of the volume indicated by the last used values of [, S7] and |. 
[,D#] is used in place of the prefix. 


By the Way: You can access any file using just its pathname. The [S+] 
and [,D&] options are primarily for OOS compatibility. ey are also 
useful if you don't remember a disk's name. 


For Example—-[pn] 


Here are a few ProDOS commands that use the pathname option: 


3 dE 


"BIG 


pues 


n mwa 


۳ 
eR LE 
8 


ÁJPRÜDCRBRHZ 


nn 
£r1 


= m d 
a mr 


an 
TS 
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Did you try these commands? If not, try them in the order 
presented. How they work is explained in later chapters. 
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The Slot Number Option —[, S] 


[S2] inciude this option to tell ProDOS the slot that connects the 
disk drive you want to access. Replace # with a slot 
number from 1 to 7. 


When you use this option, the value specified by # becomes the 
default siot number. 


If you use this option without the drive option, drive 1 is assumed. 


If this option is used after a pathname, ProDOS first looks for that 
path in the indicated slot. if this option is used after a partial 
pathname, ProDOS forms a pathname by adding the volume name 
of the indicated volume to the partial pathname (the prefix is 
ignored). 





The Drive Number Option—[,Dz] 


[LD&] Include this option to tell ProDOS the drive that contains 
the disk you want to access. Replace £ with drive number 1 
or 2. 


When you use this option, the value specified by # becomes the 
default drive number. If you use the drive number option without a 
slot number option, ProDOS looks for the drive in the default slot. 


If this option is used after a pathname. ProDOS first looks for that 
path in the indicated drive. If this option is used after a partial 

pathname, ProDOS forms a pathname by adding the volume name 
of the disk in the indicated slot and drive to the partial pathname. 





Warning 

If you use the siot number and drive number options to indicate a drive 
that is not there, you will get the HC: DEVI CE CONHECTELD error 
message. 





Options 
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For Example—{,S4] LDR] 


Here are some ProDOS commands that use the [,S#} and [, 0#] 
options. Try them in order now with the /EXAMPLES disk in 
drive 1. 


CAT PRUGRAMS S. 


4 
ب‎ m d 


bil 
11 


A 


displays the files in the PROGRAM directory of /EXAMPLES, the 
disk in slot 6, drive 1. 


Seer Ti m i 
PED £6 


all 
f 


Ll 


sets the prefix to the name of the volume directory, slot 6, drive 1. 


EN SOEWRBMPLEZ-FEUGEBMZ-HIZEOUM 25 اس‎ 


it.‏ اپ انا اس کت 
سن ما ےک ا fee‏ سو 1 1 


Do 


checks first in drive 2 for the /EXAMPLES volume, then in other 
drives untii it finds /EXAMPLES. 


سس ا llle ee‏ سب 





In Summary 


Table 2-2 shows the pathname that ProDOS seeks for each 
possible combination of the pathname, stot, and drive options. 


Table 2-2. How ProDOS Forms a 





i Pathname [pn] LS] [Dx] Pathname Sought 
: 2 - . See command description - 
| pon - - pn = prefix + ppn"* 
| ppn جرد‎ T pn = vn + pen 
| ppn + - pn = vn + ppn** 
-— ppn z + pn = vn + ppn*** 
ا س‎ pn - - pn = pn 
pn 2x 2د‎ pn = pn 
۱ Key: + = option used 
- = Option not used 
pn = pathname 
ppn = partial pathname 
vn = volume name of disk at Sz, D 


| 
| 
| 
| 


* ifthe prefix is empty, the last used values of S# and D 
are used to determine a volume name. 
** When only Sz is given, drive 1 is assumed. 
*** When only D# is given, the last value of S4 is used. 
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Using Files 


About This Chapter 


This chapter describes the ProDOS commands that let you keep 
track of and manipulate the files on your disks. You can use these 
commands 


e to see what information is on a disk 


e to create more room on a disk by throwing away obsolete 
information 


e to change the name of some information so that it is easier to 
locate 


e to protect some information from being accidentally destroyed. 


Because you issue the commands described in this chapter from 
the keyboard more frequently than from within programs, they are 
described here before the chapter that explains the technique for 
using ProDOS commands in programs. Remember that they can 
all be used in programs. 


This Chapter’s Commands 


The ProDOS commands that let you manipulate files are 
summarized below; each affects one file at a time. If you want to 
perform operations on several or all of the files on a disk, use the 
ProDOS Filer, described in the ProDOS User's Manual. 
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Using Files 


About This Chapter 


This chapter describes the ProDOS commands that let you keep 
track of and manipulate the files on your disks. You can use these 
commands 


to see what information is on a disk‏ ٭ 


e to create more room on a disk by throwing away obsolete 
information 


e to change the name of some information so that it is easier to 
locate 


e to protect some information from being accidentally destroyed. 


Because you issue the commands described in this chapter from 
the keyboard more frequently than from within programs, they are 
described here before the chapter that explains the technique for 
using ProDOS commands in programs. Remember that they can 
all be used in programs. 


This Chapter's Commands 


The ProDOS commands that let you manipulate files are 
summarized below; each affects one file at a time. If you want to 
perform operations on several or all of the files on a disk, use the 
ProDOS Filer, described in the ProDOS User's Manual. 
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CATALOG List all the fifes in a directory 


Use this command to place a list of all the files in the directory you 
name onto the screen. It also displays other information about 
each file. 


PREFIX Set a directory to work in 

Use this command to set the value of the prefix, that is, the 
pathname that is automatically added to the beginning of any 
partial pathname you use. You can also use it to display the prefix. 
CREATE Create a new directory (or other file) 

Use this command to create a new file with a name-and type that 
you specify. Although there are ways to create other file types, this 
is the only way you can create a new directory. 


RENAME Change a file's name 


Use this command to change the name of a file, but you cannot use 
it to move the file from one directory to another. 


DELETE ‘Remove a file from a disk 


Use this command to remove a file from its directory. Once you 
delete a file, it is not possible to get it back. 


LOCK Protect a file from being destroyed 

Use this command to protect a file from being accidentaily 
destroyed. Once you lock a file, it cannot be renamed, deleted, or 
otherwise changed until it is unlocked. 


UNLOCK Unprotect a locked file 


Use this command so you can rename, delete or otherwise change 
a file that is locked. 
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Figure 3-1. Using Files 









My name is 
/NEWDIR 





Make 2 
new directory file 
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My name is 
{DISKO /MYDISK /DISKO 


RENAME: 
Give a file a new name 


سے £99 جا ———— ہے rm m‏ سو سس سے 


My name is Prefix is 





PREFIX: 
Set a directory to work in 


E What files are 
in a directory? 


My name is 


UNLOCK: 
Unprotect a file 


DELETE: LOCK: 
Remove a file Protect a file 
from its directory 1 


The CAT and CATALOG Commands 


To view the names and other characteristics of all the files in any 
directory, use one of the two forms of the CATALOG command: 


CAT [pn] [,S#] ,D«t] 
CATALOG [pn] [,S#] [.D#] 


Display 40 columns 
Display 80 columns 


CAT displays a 40-column wide list of files. It includes the file's 
name, type, size, and modified date. CATALOG displays an 
80-column wide list of files, which includes the same information, 
plus the date that the file was created, and some technical 
information. If you display the 80-column list on a 40-column wide 
screen, each entry in the list takes up two lines. Figure 3-2 is a 
comparison of the four displays that can be generated by this 
command. 


The CAT and CATALOG Commands 


Le opem ee moo nr 5 ہ۔ سے ہا سے‎ 





nes‏ اوم به ما ھت جا تہ نويه اس اس 





Figure 3-2, CAT and CATALOG 
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80-column CATALOG 
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HAME TYPE BLOCKS MODIFIED 
CREATED EHDFILE ۵ 
معع‎ SYS 29___1-SEF- 
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8 قق‎ 18-JUL-E73 808 512 
PROGRAMS DIR 3  1-SEP-e3 
17:51 22-08-63 8 1536 
DATA DIR 1 1-SEP-83 
17:46 28-1488-8308 512 
EXTRAS DIR 1 1-SEF-83 
8:8B  28-MHR-EZz BGB 512 | 
FOSTAGE, RATES BAS 8 -SEP-S3 - 
8:88 17-JUL-S2 0 3273 | 
RENUMBER EAS 1-SEP-83 . 
6 : وتا‎ ZS-MAR-SS 4:86 
BLOCKS FREE: 187 BLOCKS USED: 172 
TOTAL BLOCKS: 8 
/EXPHPLES 
HEE TYPE BLOCKS MODIFIED CREATED EHDFILE SUBTYPE 
PROMIS st W HSE جم ںےہ جع‎ ITE — MEX 
RAST ےر‎ SY35 —— 21  1-8EP-ED 09A جورم‎ 21104 1824 
STARTUP BAS 7 جوز‎ fll الل‎ 8:00 98 
HLF BIN 1 OIL DULG UZ? 
HELPSCREENS TT SS {FPA mio بے ارت‎ Mae 12750656 
DIRECT OF i جج‎ 86 EE وھ‎ Sl 
PRACTICE OIF — 1 {GFF G E-JUL-BT ete 512 
PROGRAMS DIR 3 وق 28-88-02 17:51 تور‎ — 1536 
DATA DR — 1 1-8EP-02 17:446 تسود‎ ۵8 Si 
EXTRAS DIE — 1 و 17:53 می‎ ue S 
POSTAGE.PATES GSS 8 دز‎ 086 {7-LE 8:8 7 
27 BAS I-SEP-82 BO 26-42-57 0:00 
ELOCKS FREE: 187 BLOCKS USED: 173 TOTAL BLOCKS: 2% 
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For example, to see the files of jokes in the directory 
/JOKES/BAD, you can use the command in either of the following 
forms: 


Display 80 columns. C 
Display 40 columns. A 


The Options 


if you give the CAT or CATALOG command without any options, 
the names and characteristics of ail the files in the prefix directory 
are displayed. If the prefix is empty, all the files in the volume 
directory indicated by the last used values of {,S#] and [, D#] are 
displayed. 


[pn] The filename used in the command r must indicate a 
directory file or you see the FILE TEE MISMATCH error 
message. 


[S4] f you use the slot and drive options without a filename, 
[LD&] ProDOS displays a list of the files in the volume directory 
of the disk in the specified drive. 


——wOI—— — Á———U———————P'O———ys' '—"H—"——T 
For Example 

To see a list of the files in the volume directory of the /EXAMPLES - 
disk, type 


> m. 


CAT «EXAMPLE 


my 


and you see the display shown in Figure 3-3. 
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Figure 3-3. A Catalog of the 
/EXAMPLES Disk 
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Now, be sure that your /EXAMPLES disk is in slot 6, drive 1; type 


CAT! 


T; 


EDI 


and you see a 40-column tist of the same directory. The first 


example causes a display of the files in the volume directory of the 


volume named /EXAMPLES, no matter which disk drive 
/EXAMPLES is in. The second example causes a display of the 


names of the files in the volume directory of any disk that is in the 


drive connected to slot 6, drive 1. 


Now look at the files in another directory. Notice that one of the 


files displayed on the screen is named PROGRAMS. Type 


1 


and a new list of files appears on the screen. These are the files 


ot 


Ed 


bao‏ و و سر 
APPLE‏ بب جح 


“FR 


eve 
EB 


er 


stored on the /EXAMPLES disk in the directory named 
PROGRAMS. 
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Figure 3-4, A Catalog of 
/EXAMPLES/DIRECTORY 





What It All Means 


By now you must be a little curious about the meaning of the 
headings that appear on the screen each time you use the 
CATALOG command. Wonder no more, for curiosity killed the 


CAT. Type 


TALOG ٣۳ 


and, if you have an 80-column display, you see the catalog shown 


in Figure 3-4. 
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This is the 80-column version of this command. If you have a 
40-column display, you see the same information, but each entry in 
the list takes up two lines on the screen. 


The Directory's Name 


The filename of the directory whose files you see in Figure 3-4 
appears in the upper-left corner of the catalog. If it is a volume 
directory, it is preceded by a slash; otherwise it is not. 
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Table 3-1. The File Type Abbreviations 


The uses tor each file type are explained 
later in the manual. 


A block is a 512-byte unit of disk space. 


NAME (Filenames) 


The name of each file in the directory is listed beneath the leftmost 
heading, the one labeled HAME. If the named file is locked, its 
filename is preceded by an asterisk. 


TYPE (File Types) 


The abbreviations beneath the heading labeled TFE tell you the 
type of each file in that directory. The file type that corresponds to 
each abbreviation is shown in Table 3-1. 


سس MM‏ ممم 


Abbreviation File Type 


DIR Directory 
TXT Text 
BAS Applesoft Program 
VAR Applesoft Variables 
BiN Binary 
REL Relocatable Code 
" SFH User Defined 
SYS ProDOS System File 
SYS ProDOS System Program 


* # is an integer from 1 to 8. 
ا‎ eee ee لس‎ 


Notice that a file of each type is represented in the 


/EXAMPLES/DIRECTORY directory. With ProDOS started up and 
the /EXAMPLES disk in drive 1, type 


ri 


HELF Fik 
to see this list of file type abbreviations. 


BLOCKS (File Sizes) 
ELZOCEZ fists the number of blocks of disk space that 
each file uses. 


For directory files, this column lists the number of blocks used by 
the directory file, but not the blocks used by the files in the 
directory. 


When you catalog a volume directory, the block use of the entire 
disk is displayed at the bottom of the screen. 
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Chapter 7 describes random-access 
text files and explains how this might 
happen. 


Table 3-2. The SUBTYPE Column 
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MODIFIED and CREATED (File Dates) 


These columns contain the dates and times at which you created 
and last modified your files. The first half of the “lO نع‎ 
column is displayed by the CAT command; both columns are 
displayed by the CATALOG command. These dates and times are 


correct only if 
٭‎ you have a Thunderciock™ or 
© you have used the TIME program, described in Appendix D, or 


© you have some other type of clock/calendar card, and have set 
it up as explained in Chapter 9. 


If there is 2 Thunderciock interface card in one of the Apple 5 
slots, ProDOS recognizes the card and sets itself up to read the 
date and time from the card. 


ENDFILE (Maximum File Sizes) 


EHDFILE lists the number of bytes that each file will use if all the 
disk space allotted to that file is filled (sometimes it is not). 


SUBTYPE (File Properties) 


ZLUET"YFE lists important properties of some types of 
files. A single letter precedes each number in this column. The 
letters used are shown in Table 3-2. 


Letter Meaning 


A Load Address: This is the memory address from 
which a binary file (BIN) was saved. The address is 
given in hexadecimal. 


R Record Length: This is the size (in bytes) of each 
element in a text file (TXT) or user defined file 
($F &). The length is in decimal. 


For example, binary files are usually placed in the same part of 
memory each time they are used. For a binary file the property in 
the ZE TTFE column starts with an A (for load Address) followed 
by the memory address at which that binary file was last placed. 
This type of attribute is discussed in Chapter 4, "BASIC Programs 
in Files." 
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The other type of property begins with an R (for Record length). It 
specifies the size of each element of the file. This attribute is 
explained in Chapter 6, "Text in Files." 


The Bottom Line 


When you display the catalog of a directory, the bottom line of the 
display describes how space on the volume is used. 





E: DEZ FRIE is the number of unused blocks on the 
disk, EL: = ic ZEG is the number of full blocks on the disk, and 
TOTAL ELOZES is the maximum number of blocks of information 


that the disk can hold. 


The PREFIX Command 


If you are going to be referring to several files in a single directory, 
the PREFIX command can save you some time. Use the PREFIX 
command to set the prefix to the name of the directory the files are 
in; you can then refer to the files by filename alone. 


To assign a new value to the prefix, or to see the current value of 
the prefix, use the command: 


/PREFIX [pn] [,S#] [,D#] 


For example, if the prefix is set to /EXAMPLES/, and you want to 
use the file named /MAMMALS/RODENTS/BEAVER you must 
refer to it by its full pathname. If you use the command 


mr 
e j س2‎ 
deor 


FRE! 
you can then refer to the file simply as BEAVER, and to the other 
files in the directory as MOUSE, SQUIRREL, RAT, and so on. 


When you start up /EXAMPLES or any other ProDOS disk, the 
prefix is left empty, and the slot and drive defaults are set to 
indicate the drive containing that disk. Whenever the prefix is 
empty, ProDOS looks for files on the disk in the indicated slot and 
drive. 


The PREFIX Command 





The Options 


If you use the PREFIX command without any options, the current 
value of the prefix is displayed on the screen. 


(pn] pn must be the pathname or partial pathname of a 
directory file. Unlike a normal pathname or partial 
pathname, it may end with a siash. If it is not valid, you will 
getaF ILE ۲٠۳ج‎ MISMATCH or FILE HOT FÜLIHD error. 


If you use a slash instead of a pathname, the value of the 
prefix is left empty. 


[,S#] If you do not specify a filename, but you do use the 

[DX] siot and drive options, the volume name of the indicated 
disk is assigned to the prefix. If you have a controller for a 
single disk drive in a slot, refer to it as drive 1 of that slot. 





For Example 


With ProDOS started up, and the ProDOS disk in drive 1, set the 
prefix to indicate the /EXAMPLES voiume directory using the 
command 


bela 


PREFIM -EMAMPLE: 


; and then make sure the command worked right using the 
i command 


PREF 2 
Notice that the vaiue of the prefix is printed out as 


oERAMPLES 


ttl 


If the prefix value that you assign doesn't end in a slash, ProDOS 
automatically adds one. It does this so, when the prefix is attached 
to a filename or partial pathname, a proper pathname is formed. 


وا 
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Refer to Chapter 5, “Programming 
With ProDOS," for details on reading 
the prefix. 





Verify that you can enter the prefix with a trailing slash by typing 


r. p ۱ ۶ 347 4 4 m 
EFEEFix :;EZHHFLE 


pun 


un 


and checking the result using the command 


If you want to set the prefix to the name of the volume directory of i 
one of your disks, but you can't quite remember the disk's name, ۱ 
use the siot and drive options to indicate the disk's location. For 

example, 


Li 


Dn 
(Ta 


PEEP Les 


sets the prefix to the value /EXAMPLES/. Try it. If your disk has a 
tong name, this form may be shorter than typing in the entire 
volume name. 


If you want to look at or use some of the programs that are 
supplied with your /EXAMPLES disk, type the command 


mee ere oe 


- الا 


© نے ای رس rs‏ سم مر ہو ہم 
ج8۴۰ ےر FEEFIX‏ 


You can now see a list of the programs in this directory by typing 


IT 
and you can reter to any one of them by filename alone, as in 


Ik] - ينم‎ me 


EUH HAE 0ت‎ 
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When You Use PREFIX in a Program 


When you use the PREFIX command with no options from within a 
program, the value of the prefix is not displayed; it is set up so the 
next INPUT statement in the program reads it. 
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The CREATE Command 


The primary purpose of the CREATE command is to create 

directory files within which you can place other files. Although you 
can use thís command to create files of all types, most of the other 
file types are created automatically by other ProDOS commands. 


A volume directory file can store the names and locations of up to 
51 files. It isn't really necessary to create more directory files 
unless your disk will contain more than 51 files. However, a well 
planned set of directories can make your files much easier to find 
and use. 


Be Prepared: Create your directory files before you have files to place 
within them. It is much easier to place new files in a directory than to 
move existing files from one directory to another. If you must do this, 
use the file copy option of the ProDOS Filer. 


You create a file by using the command 
CREATE pn [,Ttype] [Sz] [.D&] 


Notice that the CREATE command uses a new option, Ttype, that 
determines the type of file to be created. If you do not use this 
option, a directory file is created. To create a file of any other type, 
you must use this option. 


For example, you can create a directory file named 
/BUDGET/CHILDREN by using the command 


-— WU DE ETN 
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ul 


CRERTE 


F 





Directory File Size 


The number of files that fit into a directory other than a volume 
directory is limited only by the amount of space on the disk. The 
size of a directory file is determined by the number of files it 
contains. 


The first block of disk space used by a directory can hold up to 
12 files. Each subsequent block used by a directory can hold up to 
13 files. Thus a directory with 27 files in it is three blocks long 

(12 files in block 1, 13 in block 2, 2 in block 3). 
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Chapter 2 discusses the directory file 
type: the other types are explained as 
you need to know about them. 


Table 3-3. The File Type Abbreviations 


The Options 


pn pn is the pathname or the partial pathname of the file to 
be created. The file must not exist. 


[,Ttype] type is a three-letter abbreviation that determines the 
type of file to be created. The abbreviations of the 
various file types are given in Table 3-3. You can see 
these abbreviations by using the HELP FILE command. 





Abbreviation File Type 
DIR Directory 
TXT Text 
BAS Applesoft Program 
VAR Applesoft Variables 
BIN Binary 
REL Relocatable Code 
* SFz User Defined 
SYS ProDOS System File 
SYS ProDOS System Program 


* £isan integer from 1 to 8. 





[Sz] The slot option has its usual meaning. 


[Dz] The drive option has its usual meaning. 





For Example 


With ProDOS running and the /EXAMPLES disk in drive 1, set the 
prefix to /EXAMPLES/PRACTICE/ with the command 


p= =‏ پر یس زاب m mme‏ ,= 
j LP) LB‏ سا مس دی اس 


POP: L7 Sow-e- EE EP LI 


mmc کرس‎ 


We want to create a directory named 
/EXAMPLES/PRACTICE/NEWDIR. Type the command 


جى p‏ و و سر یل سس ےسا ص m,‏ ,= 
nil iii EOF RÀ‏ ا 1 


mI OLR 


and listen to the /EXAMPLES disk whirring away. Now type 


to see that the new directory exists. Notice that the catalog of files 
shows that HETI uses up 1 block of disk space. 


The CREATE Command 


To emo mE MESS m - o 


aa me —4——Ó امہ‎ 






ee موس‎ 
















fei‏ سر R‏ و ای وج hoe‏ ا ہی 
کے بای ماج ML‏ کیا iaa oe‏ 

حور S‏ هه 

ee Pp EE Iw SET 


dT SIM Main 
SEL EL “ 
Y 

بش 


: X 
2 Tac Es 
ME = : B 
A CTUM de os چا‎ ai 


The RENAME Command 


To change the name of a file, use the RENAME command: 
RENAME pn1,pn2 [,S#] [,Dz] 


This command changes the name of a file from the name indicated 
by pn1 to the name indicated by pn2. The new name must be in the 
same directory as the old name. Thus you can use the command 


T سے‎ p=, me - , ct 
PoRiiliir- Sm 


11 


mT اس‎ 


111 
per 


m‏ ہبہ 
joe‏ 





to change the name of a test recipe from FUOGE to BROWNIES, 
but you cannot use the command 


دا æ:‏ سسا 





to move your BROWNIES recipe from the TEST directory to the 
EDIBLE directory. To move a file from one directory to another, use 
the ProDOS Filer. 


You cannot rename a file that is locked. Refer to the section “The 
LOCK Command" in this chapter for further details. 





The Options 


pni,pn2 When you give a file (pn 1) a new name (pn2), the new 
name must be unique. If it already exists, you get the 


DUPLICATE FILE name error message. If 1 


does not exist, you get the FILE HOT FOUND error 
message. If the two pathnames, pnt and pn2, do not 


ب 


indicate files in the same directory, you get a 241 رك‎ 


ERREUR. 
[S4] The slot option has its usual meaning. 
[,D#] The drive option has its usual meaning. 
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For Example 


With the /EXAMPLES disk in drive 1, set the prefix to the name of 
the directory containing practice files by typing 


Now look at the files in the directory /EXAMPLES/PRACTICE by 
typing 


CRT 
The list of files displayed on the screen includes the files 
RENAME.ME.1 , RENAME.ME.2 , and RENAME.ME.3 . To change 


the name RENAME.ME.1 to RENAME.ME.4 , type 


I" 


(a. EEMBHME,.ME.* 


PEGE REH fj 
Pme! 1. س‎ i'd ار‎ ۱۱ lywe Li 


to verify that the name was indeed changed. Now rename the file 
LOCKED.UP.1 with (0 


RKEHHME LOCEED.LIP. 1. IHMATE 


Whoops! This file is locked; its name cannot be changed until you 
unlock it. tf you have valuable files that you don't want to alter or 
rename accidentally, lock them. The sections on the LOCK and 
UNLOCK commands in this chapter describe this method of file 
protection. 


The DELETE Command 
To remove a file from a disk, use the command 
DELETE pn [,S2] [,D#} 


For example, you can remove the file /RESUME/DRAFT 12 from its 
disk with the command 


ETE REEZUHE.-DERHFTiZz 
The file indicated by pn must be unlocked, and if it is a directory 


file, it must be empty. After you delete a file there is no way to get it 
back again. 


The DELETE Command 





ساسا سو و - . 








The Options 


pn A pathname or partial pathname, pn, must be included in 
the command; the indicated file must exist or you get a 


FILE HOT FOUHD message. 
[S4] The slot option has its usual meaning. 


[,D#] The drive option has its usual meaning. 





For Example 
With ProDOS started up, and the /EXAMPLES disk in drive 1, set 
the prefix to /EXAMPLES/PRACTICE/ with the command 


یو رو دہ مود 


PL 


(DL LITT: 
mR سا‎ 


m 


To see the files in the PRACTICE directory, type the command 


maT 
litl 


Included in the listed files are the files DOELETE.ME.1 , 
DELETE.ME.2 , and DELETE.ME.3. 


Now delete the file /EXAMPLES/PRACTICE/DELETE.ME.1 using 
the command 


سے سن مر 
tite €!‏ 
سس سا اما 


- 
{ 


۱1۱ 


ME. 


۳۹ 


0 


m 


= 
LI 


IT 


Try deleting the other DELETE.ME files using a full pathname, and 
by setting the prefix to something else, /EXAMPLES/ for example, 
and using a partial pathname. 


Use the CAT command to verify that the deleted files are no longer 
on the disk. 


The LOCK Command 


At times you wil! want to protect individual files from being 
accidentally renamed, deleted, or altered. You can do this using 


LOCK pn [,S4] (,Dz] 


For example, you can lock the file /INVENTORY/NOTE.PADS by 
typing 
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While a file is locked, it cannot be renamed, deleted, or altered. 
Any attempt to change a locked file causes the F i_2 ۱-۳: 
error message to be displayed. To alter a locked file, you must first 


untock it with the UNLOCK command. 


When you catalog the files in a directory, the locked files are 
marked by asterisks to the left of their filenames. 


You cannot lock a volume directory file. You can, however, protect 
an entire flexible disk by covering its write-enable notch. 





The Options 
pn pn is the pathname or the partial pathname of the file 
to be locked. You cannot lock a volume directory. 


[Sz] The slot option has its usual meaning. 


[Ds] The drive option has its usual meaning. 
 ——  —— ——n— à ————————————— Ó——— ——————!MP— m ——"m 
For Example 


With ProDOS started up and the /EXAMPLES disk in drive 1, 
display a list of the files in the PRACTICE file using the command 


Dim wool Rabe 
jf “Eee be 


1i td Lc‏ وو سر 


Notice that the files LOCKED.UP. 1 and LOCKED.UP.2 both have 
asterisks by their file types, indicating that they are locked. First 
set the prefix to /EXAMPLES/PRACTICE using the command 


: ہی و ای a‏ فرط وج اد Cc‏ 
F SHMPLEZ.FERLI‏ 


۳11 


Tom 
L2 


mi 
CY 


Cı 1 ئ5‎ € 
eee Pos ۳ 
POPs fame hi: حا إن‎ 


Next lock the file LOCK.ME.1 in the prefix directory with the 
command 


mj Tus MI 


i p! E Sos BS 
ie اساسا :م اا‎ E i 


Use the CAT command to verify that the file is now locked. 


The LOCK Command 
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The UNLOCK Command 


Before you can delete, rename, or otherwise change a locked file, 
you must UNLOCK it using the command 


UNLOCK pn [,S&] [,D#] 


For example, to unlock the file /INVENTORY/NOTE.PADS so that 
you can update the information it contains, use the command 


Pag Lee? T had i R iiir: 
nif کا‎ Pde bE 


111 

El 
Ti 
L1 
KE 


IT 
PIRE 


ae sol!‏ ےا 


You can UNLOCK any file except a volume directory file. Volume 
directory files cannot be locked. 





The Options 
pn pnis the pathname or the partial pathname of the file to be 
unlocked. 


[S4] The slot option has its usual meaning. 


[Ds] The drive option has its usual meaning. 





For Example 5 


With ProDOS started up and the /EXAMPLES disk in drive 1, 
display the list of the files in the PRACTICE file by using the 
command 


رس em‏ نب 
Em |‏ اه : ہی ۳ 


FERI 


=p ps 


i 


Loa 


Notice that the files LOCKED.UP.1 and LOCKED.UP.2 both nave 
asterisks by their file types, indicating that they are locked. First 
set the prefix to /EXAMPLES/PRACTICE/ using the command 


-— £47 


- تا سا یت i C‏ سا 


fein atts تھے‎ Aa 


Next unlock the file LOCKED.UP.1 in the prefix directory with the 
command 


! 17: F, qme met و‎ 4 
ee. beable RE RI ad 


Use the CAT command to verify that the file is now unlocked. 
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BASIC Programs in Files 


About This Chapter 


This chapter describes the ProDOS commands that let you use the 

BASIC programs on your disks. If all you want to do is run 
programs that are already on your disks, pay special attention to : 
the - (DASH) command. This command moves any type of 
program from a file on a disk into memory, and then starts it i 
running. DC 


You can use the commands in this chapter 

e to bring a program into memory and run it 

e to bring a program into memory without running it 

e to store the program that is currently in memory on a disk. 


These commands are most useful when you are writing programs 
or modifying programs that already exist. 


BASIC Program Files 


Although the Apple ۱۱ can use two dialects of the BASIC 
language—Applesoft and Integer BASIC—ProDOS supports only 
Applesoft. To use ProDOS, your Appie ۱۱ must have Applesoft 
BASIC in Read Only Memory (ROM), and at least 64K of Random 
Access Memory (RAM). 


When you start up /EXAMPLES, it displays the message 


e Tit "TRA‏ سے س الس مم سے کس 
ا ۳ ۱ i me fT h.:‏ 
٩۶‏ ( ۶ و | | dj‏ ماد إ ہچ طط pe‏ لسو $i‏ 

i C E‏ اس ساسا : 35 أ 


telling you that the Applsoft language is indeed in Read Only 
Memory. 


BASIC Program Files 
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The EXEC command is described in 
Chapter 8. 


Binary program execution: see also the 
DASH command. 


met I Huc‏ موس سب یروس جرب 
Lot rea A nh‏ لت ما Lis‏ سم ماس عو acm‏ 





i EXEC program: see Chapter 8. 
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This Chapter’s Commands 


This chapter's commands are summarized below. Each causes the 
transfer of a program between memory and a disk file; the 
direction of the transfer and the type of file transferred are 
determined by the command you use. 


- (DASH) Run any type of program 


Use this command as a short form of the RUN, BRUN, and EXEC 
commands. it causes a BASIC, binary, EXEC, or system program 
to be transferred from a disk file into memory and then executed. 
This is the command you use to run the ProDOS Filer without 
starting up /USERS.DISK. 


RUN Run a BASIC program from a fiie 


Use this command to copy a BASIC program, type BAS, from a 
disk file into memory to be executed automatically. 


LOAD Get a BASIC program from a file 

Use this command to copy a BASIC program, type BAS, from a 
disk file into memory. Once the program is in memory, you can run 
it, modify it, or save it in a disk file. 


SAVE Save a BASIC program in a file 


Use this command to save the BASIC program that is currently in 
memory as a BASIC disk file, type BAS. 


The - (DASH) Command 


Ons of the more useful features of ProDOS is the - (DASH) 
command. With this command you can bring into memory and run: 
a BASIC program, a machine-language program, an EXEC 
program, or a system program such as the ProDOS Filer. 

To run a program of any one of these types, use the command 


- pn [S4] LD#] 
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Figure 4-1. BASIC in Files 


To learn more about the way programs 
run, read the sections “The RUN 
Command" in this chapter and “The 
BRUN Command" in Chapter 9. 





BASIC program in memory BASIC program 


0 کت 
ال [ 
E‏ = 


LOAD 
ا ترا‎ ee ا‎ 








٣٢۹8۳٣ SD, R | Both RUN and - cause‏ ...۔۔ ہم 
a program to be i‏ 
loaded. then executed :‏ 





When you run a system program, everything else in memory is 
destroyed. If you are writing a BASIC program, be sure to save it i 
before running a system program. : 


For example, to run the ProDOS Filer, place the disk /USERS.DISK 
in one of your disk drives and type 


وج دز( 
EF‏ 


۲ ۲ ۳ مس‎ ۲1 EE 
لس‎ lc 3 


ee 


The Options 


pn pn is the pathname or partial pathname of the file 
containing the program you want to run. The file must be 
of type BAS, BIN, TXT, or SYS. tf the file is a binary file, it is 
loaded to the address from which it was last saved. All 


5.7.9011 سے رر ےک ۳ بر 


other file types cause the FILE FYFE HIZR | LF error. 
[Sz] The slot option has its usual meaning. 


[.D#} The drive option has its usual meaning. 


The - (DASH) Command 
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The - (DASH) command is described 
earlier in this chapter. 





For Example 
With ProDOS running, set the prefix to indicate the PROGRAMS 
directory with the command 


PREFIX «EMOMPLE: 
-^u lu » 3 — 0 مسب‎ 


tii ke 


Se 


Lit 


DI 


T mt 


Look at the programs it contains by typing 
CAT 
Now try running a binary program (type BIN), a BASIC program 


(type BAS), and an EXEC program (type TXT) by typing a dash (-) 
followed by the filename of the program you want to run. 


To run the Filer program (type SYS), place /USERS.DISK in a drive 
and type 


To return to ProDOS from the Filer, be sure that /EXAMPLES is in 
a drive, type (Q)from the main menu, type the pathname 
SEWRHPLEZ-ERZIC,and press (RETURN). 


By the Way: if you want easy access to the Filer, use the Filer program 

to copy the file /USERS.DISK/FILER to a disk that you usually have in a ~ 
drive. Then you can use the Filer by typing the DASH command rather 
than starting up /USERS.DISK. 


The RUN Command 


To run an Applesoft program that is stored on a disk, use either of 
the commands 


RUN pn [,@4] [,54] [.D#] 
- pn [,S#] LD] 


Only the RUN command is described here. 


When ProDOS sees the RUN command, it finds the file indicated 
by pn, brings it into memory, and then runs it (beginning with 
line @# if you use that option). For example, to run the BASIC 
program named CHECKBOOK on a disk named /ACCOUNTS , 
use the command 
RUH -ARCOUHTS-CHECE BOGE 


et‏ مأ ےا 
سے لان 


! اے! ۳۳۳۷ he f‏ اراح 


Chapter 4: BASIC Programs in Files 








س س س 


When a program ends, you can run it again by using the BASIC 
command 


Notice that in the general form of the RUN command, the filename 
is not optional. When you type in a command, ProDOS checks to 
see if it is a ProDOS command. If it isn't, ProDOS gives the 
command to BASIC. In this case, RUN without a filename is not a 
valid ProDOS command; the command is passed to BASIC, and 
BASIC runs the program in memory. 





The Options 
pn pn indicates the file to be run. The file to be run must be of 
type BAS (Applesoft BASIC). 


[,@#] If you use this option, the program begins running at the 
line number specified by +. If you omit this option, 
execution begins at the lowest numbered line in the 
program. 


[Ss] The siot option has its usual meaning. 


[Ds] The drive option has its usual meaning. 





For Example 


With ProDOS started up, and the /EXAMPLES disk in drive 1, set 
the prefix to indicate the /EXAMPLES/PROGRAMS volume 
directory using the command 

FREFIX «EXMAMP 


“+ hee i 


Look at the files in the PROGRAMS directory with the command 


CAT 

Do you see a program named Til. LIHEF ۶ Run the program by 
typing 

RUM THO.LIMER 


and the screen displays the words 


4 Tole of حر رم‎ Am 
4. I'M LIME zh. 


"Pa کاو‎ 
fF ° ۵ 1 arl 


سپ 


iL 
i di طط سا شا‎ 


The RUN Command 
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But if you run part of the program using the command 


RUM THU, LIHEF B25 
you just see 
1'M LIHE 5 


If you examine the program by typing 


T 
i 


DN 


LI 


you'll discover that line 20 contains that sentence. 


SE Lu Ihe LOAD Command 


To transfer a BASIC program from a file to memory, use the 
command 


LOAD pn [,S#] [,D4] 


program. It is not necessary to load a program before you run it; 


i 
| ۱ This command is useful if you want to examine or modify a 
| the RUN command automatically loads a program into memory. 





۹ Warning 
When a new program is loaded into memory, all records of the previous 
program are erased from the Apple ۱۳5 memory. If you want to save the 
The STORE command is described in variables that were set by a previous program, use the STORE command. 
Chapter 5. 





When you LOAD the contents of a file into memory, the file on the 
disk remains unchanged. 


M 
ہے ا س ا‎ 


Once a program is loaded into memory, you can run it by simply 
typing ۰ 


يي يبي يبي سر p‏ 


۱ The Options 
pn pn must indicate an Applesoft program file (type BAS). 


اس ————— 


| [S4] The slot option has its usual meaning. 


[,.D#] The drive option has its usual meaning. 
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For Example 


With ProDOS started up, and the /EXAMPLES disk in drive 1, set 
the prefix to indicate the /EXAMPLES/PROGRAMS volume 
directory using the command 


ید ہا سس سے سو سو بت عفر و ہے مم ہہ سا سم nel‏ یسر سم 
7۶ لس ام T Ru Mi EE‏ سے ہے EL‏ 
ti ۶۶ i| — 0 523.0 gd be‏ سے E‏ 0 0 


wy 
tre 


Type HEL: to remove any BASIC program from memory, then type 
آ5 1 أ‎ just to prove that there is no BASIC program in memory. 
Now, bring a new program into memory with the command 


You hear the disk drive working away, then the BASIC prompt 
returns. To see the program that was just loaded, type 


Lii 


It is important to realize that when you load a file, a copy of the file 
is transferred from the disk to memory, but the original copy of the 
file remains unchanged on the disk. For example, even though you 
have already loaded WHIZBOOM, type the command 


ZAT 


and you see that the file is stili on the disk. To place the BASIC 
program that is currentiy in memory into a file, use the SAVE 
command. 


The SAVE Command 


To transfer the BASIC program that is currently in memory to a file 
on a disk, use the command 


SAVE pn [, S2] [,D#] 
The file is saved as an Applesoft file (type BAS). 


For example, to save the current program in a file named 
/BEDTIME.STORIES/A.FRIENDLY.OGRE , use the command 


٦ 


۰ DT 
. I 


opie mu E a بت‎ ١ - تحت ۲ سے درا کے رس سو کی ا ون سر یر‎ tns mq mm 
(RUE  CBEDTIME.ZTOEIEZ-H,FREIEHULY,UGZGEE 


r1 


If you save a program to a filename that already exists, the file 
must not be locked, and it must be of the same type as the 
program (type BAS). 


The SAVE Command 
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Warning 

If you are working with several different program files at once, and there is 
a chance you will save a program to the wrong file, LOCK each file after 
you save to it, and then UNLOCK it before you save to it again. This is the 
best way to protect valuable BASIC programs. 





By the Way: You can use the SAVE command to rearrange program 
files. If you use the LOAD command to bring a program into memory, 
you can then use the SAVE command to save it on a different disk (you 
would then have two copies of the same file). Remember that when you 
load a BASIC program from a file, the fiie itself does not change. 


—Á AU — WoM——ÁÀ—— E D 


The Options - 


pn pn is the pathname or the partial pathname of the file in 
which you want to save the current program. if pn already 
exists, it must be unlocked. 


[S2] The slot option has its usual meaning. 


[D&] The drive option has its usual meaning. 


سس 
For Example‏ 


With ProDOS started up, and the /EXAMPLES disk in drive 1, set " 
the prefix to /EXAMPLES/PROGRAMS with the command 


FREFIX :;EXRMFLES.PRÜGRERMZ. 

Now load a very short program into memory with the command 
LIAD VERY. SHORT 

To see how short this program is, type the command 


EUST 


(in 


and you see before you a single line of program which reads 


iM PEIHT "A VERY SHORT PROGRAM" 


ate! 
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Even if you aren't a programmer, you might guess that this 
program does one and only one thing: it prints the words F VERY 
SHORT PEUZGRERH onto the screen. To see it do its very short 
thing, type 


لاع 


Remember that the RUN command without a filename is not a 
ProDOS command; it is a BASIC command that causes the 
program that is currently in memory to be run. 


Now for the fun part. Save the program to a different disk file, say 
/EXAMPLES/PROGRAMS/ONE.LINER, with the command 


w m کے‎ i کس و‎ 
Tal! MME. LINER 


You can see that the program has found its new home by typing 


mm 
بسا‎ + 
Lari 


Notice that the first copy of the program, VERY.SHORT, is stil! on 
the disk. Notice also that a program, even after a SAVE, remains in 
memory. Use ۱۰۲ or LI ZT to see that the program is still there. 


If you have an Apple lle with an Extended 80-Column Text Card, 
you can also save this program to a file on the volume named 
/RAM. Type the command 


RUE RAMONE, LINER 


You can see that this version of the program has been saved by 
using the command 


Notice how much faster /RAM is than a normal disk volume. It is 
most useful when you are developing a large BASIC program and 
you wish to save intermediate versions of it frequently. 


The SAVE Command 
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Programming With ProDOS 


About This Chapter 


This chapter contains an overview of programming with ProDOS. It 
describes 


e the startup process and how to make a startup disk 

e how to use ProDOS commands from within a program 

e how to read the prefix from within a program 

e how a program can handle errors 

e how your programs can communicate with devices in slots. 
You should have some experience with Applesoft BASIC. If you did 
all the exampies in the App/esoft Tutorial, you know enough. If you 


didn't, you should work your way through it before continuing with 
this manual. 


If you know Integer BASIC, but not Applesoft, read the appendix in 
the Applesoft BASIC Programmer's Reference Manual that 
summarizes the ditferences between the two. 


This Chapter's Commands 


The commands described in this chapter are summarized below. 
This is not meant to be a complete description of each command, 
it simply gives you an idea of the use of each command and of the 
way the commands are interrelated. 


CHAIN Run a program, but save the variables 


Use this command to run a new program. Unlike RUN, it does not 
cause the variables that are already in mernory to be thrown away. 
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Figure 5-1. CHAIN 


Figure 5-2. STORE and RESTORE 








CHAIN: 
Loads new program 


BASIC 


Program Variables 





Replaces No change 


STORE Save the variables in memory to a file 

Use this command to save in a file all the BASIC variables that are 
currently in memory. You can retrieve these variables by using the 
RESTORE command. 

RESTORE Get BASIC variables from a file 


Use this command to discard the variables that are currently in 
memory, and to bring in new variables from a file. 


RESTORE: 
Load variables 


No change Replaces 


BASIC BASIC 


Program Variables 





No change No change 


STORE: 
Save variables 
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PR# Send output to a slot 


Chapter 9 explains how to use PR= to Use this command to cause the characters that are normally 
send output to a program. printed on the screen to be sent to a device, such as a printer, ina 


slot. 


IN# Get input from a slot 


Chapter 9 explains how to use IN= to Use this command to cause characters to be read from a device, 
get input from a program. such as an external terminal, in a slot instead of from the 
Figure 5-3. PR= and IN= keyboard. 


Slot N 








Write characters 
to screen Write characters 


to slot N 
2۸ 5 





Screen 






PR= N 








Program that 
reads and writes 
characters 





fam INS N 


o 
ww? Read characters 


trom siot N 
Read characters 


from keyboard 


Keyboard 
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A ProDOS startup disk contains ail the 
information needed to bring ProDOS 
into memory and start it running. 


Examples of STARTUP programs are 
given later in this chapter. 
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What Is a Startup Disk? 


Every Apple ۱۱ system has a particular disk drive known as the 
system's startup drive. The startup drive is connected to drive 1 
of the disk controller card in the highest numbered siot. This 
chapter assumes that your startup drive is connected to slot 6. 


When you place a disk in the startup drive and turn on your 
Apple Il, some disks cause the system to start up, other disks just 
spin. The disks that cause the system to start up are known as 
startup disks. A startup disk contains all the crucial information 
that the Apple li needs to bring a program from a disk into the 
Apple il's memory and start a program running. 


To make any ProDOS-formatted disk into a ProDOS startup disk, 
you must copy the files containing the ProDOS program onto that 
disk. When you turn on the Appie li (or type F'F'# ۶ from BASIC) 
with a ProDOS startup disk in the startup drive, the ProDOS 
program is automaticaily transferred from disk to memory and 
run. 


Once you have made other startup disks, you will no longer need 

to use the /EXAMPLES disk each time you use ProDOS. All the 
vital parts of ProDOS are stored on each startup disk. In addition, 
by copying the files HELP and HELPSCREENS onto the startup 
disk, you can use the help feature with other startup disks. 3 


You can designate any program to be automatically run when a 
ProDOS disk is started. You do so by putting the program in a file 
named STARTUP. This file, which may contain a binary, BASIC, or 
EXEC program, can contain a program that places a greeting 
message on the screen, a favorite game, budgeting program, or 
other program of your choice. 


p _ 


The Anatomy of a Startup Disk 

A ProDOS startup disk has three characteristics: 

e It is formatted using the ProDOS Filer. 

e It has the file PRODOS in its volume directory. 

e It has a file named BASIC.SYSTEM in its volume directory. 
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To make a ProDOS startup disk: 
1. Use the ProDOS Filer to format a disk. 


2. Use the ProDOS Filer to copy the files PRODOS and 
BASIC.SYSTEM from the /EXAMPLES disk to the newly 
formatted disk. 


3. If you want a specific program to be run when you Start up that 
disk, place it on the startup disk and name it STARTUP. 


4. If you wish to use the help commands after you start up from 
that disk, copy the files HELP and HELPSCREENS from the 
/EXAMPLES disk to the new startup disk. 





The Startup Process 


When you start up your Apple tI with a proper ProDOS startup 
disk, here is what happens: 


1. The file named PRODOS, containing the most sophisticated 
parts of ProDOS, is transferred from the startup disk into 
memory and run. 


2. ProDOS examines the peripheral connector slots and tries to 
identify the type of device in each slot. It does this to determine 
which slots contain disk drives that it may need to communicate : 
with. If one of the devices is a Thunderclock, ProDOS sets itself t 
up to read from the Thunderclock. 


3. It then loads the program in the file named BASIC.SYSTEM. 
This portion of ProDOS contains all the ProDOS commands. 
This part of the program is run. 


4. ProDOS BASIC looks for a file named STARTUP on the startup 
disk. If it finds one, it runs it. If it does not find one, it displays 
the foliowing message: 


mi 
ei 
DENT 
DE] 
my 
۲۰ 
na 
1 
۳1 
m 
ra) 
DON] 
ra 


شا 
x‏ 
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Figure 5-4, The Startup Process Figure 5-4 illustrates the steps in the startup process. 


ProDOS attaches routines 
for disk drives. Thunderc!ock, 
and /RAM (if 128K). 
(4) if there is a file named STARTUP 
on the startup disk, the program in this 
file is automatically placed 
in memory and run, 
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Boot Disk 


A boot disk must have the files 
ProDOS and BASIC.SYSTEM on it. 
These files containing ProOOS are 
brought into memory (RAM) and run. 


(2) ProDOS checks to see 
۰ which cards are in 
i the slots, how much 


RAM there is, and 
if Applesott is in ROM. 


S‏ اچ چو 
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There is a (CONTROL)-(D) between " 


and C. 


CHRS (4) returns (CONTROL)-(D (۰ 


D$ contains (CONTROL )-(D ). 


Print a title. 
Print a date. 
Then list the volume directory. 
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Using ProDOS From Within a Program 


Very often it's useful to be able to use a ProDOS command from 
within a BASIC program. For example, you can use ProDOS 
commands in a program 


e to print out a disk's catalog from a STARTUP program 
e to save your budget records in a file 


e to save the condition of a game program for next time. 


To use a ProDOS command from within a program, you must print po 
a string consisting of a (CONTROL}-(D) as the first thing on a printed l 
line, followed by the command. Using the CATALOG command as : 


an example, here is one way to put (CONTROL)-(D) in a string: 


3 رس سے سر‎ tij 
ik ۳۱۲ 4 4 


fi‏ تھے .ا fo‏ ۳ رح 
D'UAT i‏ 
- ! 


PRL 


ا 


Right after you type the first quotation mark, type (CONTROL)-(0). 
Although you can't see it, it's there. 


Here is another way to put (CONTROL)-(D) in a string: 


18 PRINT CHRE Cdr "CR TALOG" 

In this example, CHR$ is an Applesoft function that returns the 
character whose code is in parentheses. The number 4 is the 
Apple li's code for (CONTROL)-(D). Note the semicolon after 

CHR$ (4). It is an optional separator between elements of a PRINT 
list, and you may leave it out if you want. 


If you set the value of a string variable. say D$, to (CONTROL)-(0) at 
the beginning of a program, simply print 02 before each ProDOS 
command in the program. This is the method used throughout the 
manual (see line 40 in the example below). 





For Example 


Here is a version of a STARTUP program that prints a message on 
the screen, and then prints out a list of the files on that disk. Type 
HEH, and then enter this program. 





5 REM APPLESOFT STARTUP 
if OF LHE 44 
بات‎ F 4T "FEU ST FROLEBHMZ 
۳1 E i mem 12285 
3E F BE i GEP, 
ais - mt 
Moo Ep 
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1 
سے مس . 


05 is (CONTROL)-(D). 
Semicolon prevents (RETURN). 


So this doesn't work. 


Ix 





Now type €; to see how it works. If you want to preserve this 
program, put a ProDOS-formatted disk in drive 1, and type 


ZALE i 


STARTUP 


el 


Debugging Your Programs 


If you are a former DOS user, you will be pleased to discover that 
the Applesoft commands TRACE and NOTRACE work with 
ProDOS. 


Use the TRACE command to cause the line number of each BASIC 
program line that is executed to be printed on the screen. Use the 
NOTRACE command to stop the printing of line numbers. 





Things to Watch Out For 


Three things you should watch out for while using ProDOS are 
described in the following sections. 


Print Each ProDOS Command on a New Line 


In a ProDOS command given from within a program, 
(CONTROL)-(D) must be preceded by (RETURN); that is, (CONTROL)-(0) 


must be the first character on a printed line. Thus, the following 
program will not work. 


iB D$ = CHR (45 
44 PRINT "RUTUMM "; 
Sü PRINT O8; "CATALOG" 


Instead of listing the volume directory, this program prints 


ths 


۱۱۲۱۸۳۱۳ CATAL 
If your program is unexpectedly printing ProDOS commands on 
the screen—and never at the beginning of a new line—this is 
probably why. 


Notice: If your program contains a statement like this, with 
preceding (CONTROL)-(D): 

D$ = CHEE £133 + CHEP i42 

your program will only work with DOS and not with ProDOS. 


Remember that (CONTROL)-(D) must be the first thing on a printed 
line. 
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Display WRITE heip screen. 





You Can't Copy Control Characters 


When you use to copy a BASIC statement, invisible control 
characters are not copied. 


Some ProDOS Commands Work Only in Programs 


Most ProDOS commands can be given from the keyboard as 
immediate commands or from within programs as deferred 
commands. Some can only be used from within programs. They 
are 


APPEND 
OPEN 
POSITION 
READ 
WRITE 


If you aren't sure if a ProDOS command can be used from 
immediate mode, simply use the HELP command. The upper-right 
corner of each help screen telis how that command can be used 
(as IMM[ediate] or DEF[erred} commands). For example, type 


and you see that this command can only be used in a program. 


Intercepting Messages to the Display Screen 


You can use several ProDOS commands to cause ProDOS to send 
information to the screen. The CATALOG command produces a 
list of files, the PREFIX command without options displays the 
prefix, and, if you use any command incorrectly, an error message 
is sent to the screen. 


ProDOS provides a way for your program to read the value of the 
prefix or the number of an error message; these are explained 
below. 


Directory files can be opened and read as explained in 
Appendix D. 


Intercepting Messages to the Display Screen 
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۱ CHR$(4) is (CONTROL )-(0). 
t Command to display prefix. 
۱ Read the prefix into PRS. 


Restore prefix to original value. 
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1 Handling 
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Reading the Prefix 


When you give the PREFIX command without options from the 
keyboard, the current value of the prefix is displayed. When you 
use the PREFIX command from within a program, ProDOS does 
not display the value of the prefix. instead, ProDOS places the 
value of the prefix so the next INPUT statement in your program 
will read it. 


You might use this feature, for example, if your program changes 
the value of the prefix, and you want to restore the prefix to its 
former value before the program ends. Here is a program portion 
that does that. 


18 D$ = CHEE O4 
28 PRINT Of; "PREFIM" 
28 IHPUT PR$ 


Rest of program which changes the value of the prefix 


IBINT 


mt 
n 


zu BRR EP Lie. "FREE 

Notice the way this feature works: You give the prefix command 
without any options, and input the prefix into any string variable, in 
this case, PR$. When you want to restore the prefix, the oid value 


is in the string. 





Handling Errors in a Program 


An error in an Applesoft program normally causes an error 
message to appear on the display screen. If your program uses the 
ONERR GOTO statement, Appiesoft puts an error number in 
memory, and then goes to the line specified in the ONERR GOTO 
statement. 


ProDOS follows the same procedure. When it encounters an error, 
it places the error number in memory, and then tells Applesoft that 
it found an error. ProDOS uses error numbers not used by 
Applesoft. Table 5-1 lists the numbers that are useful to a program 
trying to catch ProDOS or Applesoft errors. 





Number How to Read It 
Error Number PE: 22) 
Line Number PEE: 218) + PEEK (219) * 256 
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D$ is (CONTROL)-(D). 


Error handled at line 100. 
Read a filename into F$. 
Read the new name into N$. 
Give the RENAME command. 
No error; program ends. 


If it is not a FILE LOCKED error (10), go 
to line 200. 


No. don't rename the file. 


Yes, uniock the file. rename it, and then 
lock it again. 


All done. 


سے MM‏ ہے -ema‏ چ 
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For example, you cannot rename a file if it is locked. The error 


number for FILE LUCKED is 10. This small program lets you 
rename a file whether or not it is locked. Using ONERR GOTO, it 
detects the FILE | 'CEEL error, gives you a chance to unlock the 
file, then it tries to rename the file again. It also displays the error 
number and line number of any other error that might occur. 


5 REM  DHMERR,DEMO 
18 Of = CHEE £45 

28 ONERR GOTO ۵ 

20 INPUT "FILE TO RENAME? ب"‎ FS 
تاک‎ INPUT "MEM HAME? "HF 

Se PRINT OF: "REMAME ب"‎ FS)". خم"‎ 
ea EHO 


Line 20 causes line 100 to be called if there is any error. 
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148 PRINT LDf;"EEHHME ۳ : HF 
چا ۲ لس 4 جو‎ Nt Hi DE 
158 PRINT Of: "LOCK HF 
4 یس‎ Lad Sig: 
Loe EL 
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This program is saved with the name 
/EXAMPLES/PROGRAMS/ONERR.DEMO . Try it on a few of your 
locked files. 


Its operation is quite simple. Line 30 reads the name of a file to be 
renamed into F$. tn line 40 it reads the new name into N$. In 

line 50 the RENAME command is given. If there is no error, the file 
is renamed, and the program ends. If there is an error, the ONERR 
statement in line 20 says that the program should look to line 100 
for the part of the program that treats the error. 
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A complete list of the ProDOS and 
Applesott errors is in Appendix C. 


Refer to the ۸00/۵50۲۱ BASIC 
Programmer's Reference Manuali for 
more details on ONERA GOTO. 


This ONERR fixing routine is more fully 
explained in the App/esoft BASIC 
Programmer's Reference Manual. 


Line 100 checks location 222 to make sure that a F ILE LOCKED 
error (error number 10) occurred. If it was nota FILE LUCEED 
error, the program goes to lines 200 and 210, which display the 
number of the error and the number of the line where it occurred. 


If the file was locked, line 130 unlocks it, line 140 renames it, and 
line 150 locks it up again—under its new name. 
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Turning Off ONERR GOTO 


On occasion you will use ONERR GOTO to detect one error, and it 
will be triggered by another error. To prevent this, you must turn 
off the ONERR GOTO feature. To do this, use the statement 


PEE 216.4 


in your program when you want ONERR GOTO to be disabled. It is 
a good idea to use ONERR GOTO in the statement preceding the 
one that might generate the error, and to turn it off in the following 
statement. 


P———M————ÓÁÁ——————— Á———  ———! ——— 2 


Problems With ONERR GOTO 


As described in the Applesoft BASIC Programmer's Reference 
Manual, ONERR GOTO does not work quite as it should. if you 
encounter apparent problems with ONERR GOTO, include the 
following lines in your program: 


to activate this little ONERR fixer. Of course, you can change the 
numbers of any of these lines. Just make sure that line 1 is run 
before line 200 is. 
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I/O From BASIC Programs 


The remainder of the commands in this chapter enhance your 
Apple II's ability to communicate with other BASIC programs and 
with devices such as printers and disk drives that are in the 
Apple Il's peripheral connector slots. Such communication is 
referred to as the input of information and the output of 
information, collectively known as input/output or, more 

simply, 1/O. 


You can use the CHAIN command to let one program run another 
without destroying the variables that are currently in memory. 
Using CHAIN, two programs in separate files can use the same set 
of variables, or one very large program can be divided into more 
than one part. 


With the STORE command you can save the names and values of 
all your program's variables. If a program stores all its variables 
before ending, the next time you run it you can use RESTORE to 
start up exactly where it left off. 


You can use the PR# and IN# commands to let BASIC 
communicate with devices that are in any of the Apple H's slots. 


Finally, you can use the FRE command to access the fast 
housekeeping routines that ProDOS has. 


e ۱ The CHAIN Command 


If a BASIC program is too big to fit entirely in memory, you can use 
the CHAIN command to bring parts of the program into memory 
and then run each part, one at a time. All variables used, and ail 
files opened (see the next chapter) by the current part of the 
program are available to the parts of the program connected by 
the CHAIN command. 


To run part of a program without throwing away the current 
variables or closing the open files, use the command 


CHAIN pn [,@#] [,$#] [.D#] 
When you chain from one part of a program to another, the first 


part of the program is removed from memory. To use the first part 
of the program again, use the CHAIN command again. 


The CHAIN Command 
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Execution of the second program begins at the line indicated 
by [,@#], the line number parameter. If you don't use Los), 
execution begins at the lowest numbered line in the program. 





à Warning 
A chained portion of the program cannot dimension an array used by a 
previous part of the program. 


a 


[RAO ———————— 


۰ The Options 


pn on indicates the file containing the BASIC program you 
want to run next. 


L@#] If you use this option, the new program begins running at 
the line number specified by #. If the specified line does 
not exist, the next highest line in the program is run. If you. 
omit this option, execution begins at the lowest numbered 
line in the program. 


! [S&] The slot option has its usual meaning. 


[,0#] The drive option has its usual meaning. 
BENE بيس يي‎ Ma سد‎ 
For Example 0 


Here is an example of a program, PART1, that uses the CHAIN 
command with the line number option to connect a second 
program part, PART2 . Both parts are already typed in for you. Set 
the prefix to /EXAMPLES/PROGRAMS using the command 


PROGRA 


PREFIX -EMAMPLE: 


Look at PART1 and list it using the commands 


Bring PART1 into memory. 350ا‎ FART 4 
i Display it. LIST 1 
۱ You see 
ڑ5‎ REM ۲ 1 

۵8 is (CONTROL)-(0). ia چا اعد نا‎ 4% 

Set the prefix. 28 PRINT D£:"PREFIX -ESAMPLES-PROCREANS" 

Set a string value SH I£2"THE STRING If Iz PRESERVED," 

and say that it's been set. 48 |PFRIHT"FHRETi1: If HAS BEEN ۳ 
Chain to line 35 of PART2. SA PRINT ۵ : ۰۱۰۳۳۲۳۱ PARTS ,. 2.۰ 1 
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Bring PART2 into memory. 
Display it. 


This shouldn't be printed. 

If it is. skip 35. 

This should be printed 
and so should this. 


An example using tne STORE command 
is at the end of the section on the 
RESTORE command. 





The experiment here is to see if the variable I$ retains the value set 
by PART 1 when it is printed out by PART2 . Now type 


m m m e e, 
۳ ۳۱۳, ۰.۰ سے‎ 


r^ 


b Co 


us lI 
-] C 


and you see 


Cn 
KA 
we TI m 


en m eH cn 





Dg PB ke 


"nt 


If the CHAIN command in line 50 of PART1 works properly, line 35 
should be the first line that is executed, and the statement 
Poe To: RICHT LINE HLMEER, should be printed on the 


screen. If the line number option does not work properly, the first 
line in the program (line 15) will be executed first, and the 


statement, FATE: WEDHC LINE NUMEER, will be displayed. 
Line 45 displays the line PARTE: THE STEIH TE I$ 
PRESERVED if the variables are preserved, and simply displays 
PARTI: ] the variable I$ is not preserved. 


* 


Place your bets on what will be printed out, and then type 


The STORE Command 


The STORE command allows you to save to a disk file the names 
and values of all the variables that are used by a BASIC program. 
You can retrieve the variables using the RESTORE command. 


A game program, for example, can contain the STORE command 
to save the condition of a game when you stop playing. The next 
time you play the game, the program can RESTORE the variables 
from the file, and you can continue where you left off. You can also 
use the STORE command to create a set of information that is 
used by more than one program. 


To store the current variables in a file use the command 


STORE pn [,S#} [,.D#] 


The STORE Command 
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The STORE command creates and places the variables in a file of 
type VAR. 





Warning 

Because ProDOS puts the variables in a compact form before it stores 
them, there may be a considerabie time delay from when you issue the 
STORE command to when the disk drive starts spinning. 








The Options 


pn pn is the pathname or partial pathname of the file in which 
to store the variables. If the file doesn't already exist, a file 
of type VAR is created. 


[,S#] The slot option has its usual meaning. 
(Dz] The drive option has its usual meaning. 


The RESTORE Command 


The RESTORE command allows you to get from a disk file the 
names and values of a set of variables to be used by a BASIC 
program, Only a file created by the STORE command can be 
retrieved by the RESTORE command. 


To retrieve a set of variables from a file, use the command 
RESTORE pn [,S«] [,04] 


This command clears ail currently defined variables from memory 
before bringing in the new ones. 





The Options | 

pn pn is the pathname or partial pathname of the file 
containing the BASIC variables. The file must be of type 
VAR. 


[S4] The slot option has its usual meaning. 


{,D#] The drive option has its usual meaning. 
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For Example 


Your /EXAMPLES disk has a number guessing program called 
E.S.P. on it. Set the prefix to /EXAMPLES/PROGRAMS by typing 


FREFIX -:EXRHHPLEZ.-FRÜUGREHHMZ 

Then run the program by typing 

FUH Es SPs 

Play with it for a while, and then type (Q} to quit. Type 

ELIH 

again, and guess a number. Notice that the overall score starts 
at 0 again. You are going to use the STORE and RESTORE 
commands to make this program remember your overall score 
from one game to the next. Type (Q) to exit the game. 

Display the program on the screen using the BASIC command 
LIST 

Your task is to add the STORE and RESTORE commands to the 
program. Since RESTORE clears all the variables that are currently 
defined, it is a good idea to use this command as the first line in a 
program. However, before including the RESTORE command in 
the program, you must create a file from which it can read 
variables. 

Look at the last line in the program 


zag ENÛ 


This, the last line executed before the program ends, is the best 
place to place a STORE command. Type 


FEINT رمن‎ "STORE-EXAMPLES-OATA-ESP VARIABLE: 
210 EHC 
and then list the program again to be sure that the new lines are 
correct. Now when you run the program, the STORE command will 
create the new file ESPVARIABLES. Then you can add the 
RESTORE command to the program. Type 


kHH 


The RESTORE Command 
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and play the game for as long as you like; then press ) Notice 
that the disk drive whirs as the variable file is placed on the disk. 


Type 


سو رس رح 


to verify that the new file was created. Now look at the first few 
lines of the program by typing 


OTT‏ :ا oe‏ سا 


Add the line 


il 


pud 
“Tt 


EU 
eed 
I 
fi 
i 
i 
I 
l 


Once again type 


RO!‏ :سم 
m LEP‏ 


to play the game. Press any number, then look at the overall score. 


. The game now remembers the total score of all the previous times 


you played the game. To save this game in the PROGRAMS - 
directory, use the command 


Hm 


Do you have ESP? 


The PR Command 


Your Apple Il usually sends characters to the display screen. You — 
can use the PR# command to change the destination of 

characters, sending them to a device in one of the Apple 5 

peripheral connector slots instead of to the screen. The syntax is 


PRS snum 


in which snum is a slot number from 0 to 7. For example, if your 
Apple ۱۱ has an interface card for a printer installed in slot 1, the 
command 


ri 


Pew i 
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Refer to Chapter 9 for more details on 


using the PR# command to output 


characters. 


causes subsequent printed characters to be sent to the printer. To 
restore the screen as the destination for printed characters, use 
the command 


BER 





Warning 
If you are using an 80-column card, make sure it is turned off before you 
issue another PR= command. On an Apple lle, type 


(CONTROL)-(Q)to turn off the 80-column card. For other types of 80- 
column cards, refer to the card's documentation to discover how to turn it 


off. 








Warning 

Always remember to precede the PR# command with a (CONTROL)-(D) 
when you use it in a program. If you don't, ProDOS ignores the command 
entirely. If you think that your program isn't carrying out the PRZ and IN: 
commands correctly, this could be the reason. 








Starting Using PR# 


If your Appie il has a disk controller card in one of its slots, you can 
start up the disk in that-card's drive 1 with the command 


PRH snum 


in which snum is the number of the slot containing the card. It may 
seem to you that this command only sets up the disk to receive 
future characters, but PR# actually does a little more. 


When you use the PR# command to send output to a peripheral 
card in a slot, ProDOS tries to run the program in that card's Read 
Only Memory chip (most cards have them). The program in the 
ROM of a disk controller card automaticaily tries to read 
information from the disk; this is, of course, exactly what starting 
up the system is. 


You can aiso use the PR# command to call a machine-language 
program that is to perform the output of characters. 


The PR# Command 
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eto -= aw- - 
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The Options 


snum snum is the number of the slot to which you want to write. 
if snum is in the range 1 to 7, inclusive, future characters 
are sent to the device in that slot. If snum is 0, future 
characters are sent to the screen. All other vaiues of snum 
are invalid and must not be used. 
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For Example 


First save any BASIC program that might be in memory, then place 
your /EXAMPLES disk in drive 1, close the door, and type 


E RE 01 iud 


replacing snum with the number of the slot (probably 6) to which 
your Disk ۱۱ controller card is connected. Disk drive 1 whirs and 
clicks and then ProDOS starts up as if you just turned the Apple Il 
on. 


If a printer is connected to one of the Apple ۱۲5 slots, you can try 
this exampie too. First, turn on the printer. Then, replacing snum 
with the number of the slot to which your printer is connected, type 


خی ہے —-" pl‏ 
فد ار coco‏ 


The printer makes a little clicking noise. Like the disk controller 
card, the printer's card has a ROM chip that contains an 
initialization program. The printer card's program initializes the 
printer to a previously set condition, placing the head or 
printwheel to the beginning of the line, and doing whatever else 
needs to be done. Now type 


and the contents of the /EXAMPLES volume directory are printed. 
Play around with a few BASIC commands. You will find that 
everything that is normally printed to the screen is now printed on 
the printer. To return output of characters to the screen, type 
eRe جن‎ 


If your system has an 80-column card, you can now turn it back on. 
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Refer to the section on PR# for more 
details on starting up. Chapter 9 
contains an explanation of using IN# to 
input characters. 


The INZ Command 


Your Apple Ii usually reads characters from the keyboard. You can 
use the ۱۸۷۳ command to change the source of characters from the 
keyboard to a device in one of the Apple Il's peripheral connector 
slots. The syntax of the command is 


INS snum 


in which snum is a slot number from O to 7. For example, if your 
Apple ۱۱ has an external terminal connected through slot 3, the 
command 


Tk 
i 4 - 
PF 


causes subsequent characters to be read from the terminal. TO 
restore the Apple il's keyboard as the source for input characters, 
use the command 


T hidh 6 
iie Ei 





Warning 


Always remember to precede the INZ command with a [CONTROL -(D) 
when you use it in a program. !f you don't, ProDOS ignores the command 


entirely. ۰ 





You can start up the disk in drive 1 of slot snum by typing the 
command 


INz can also be used to call a machine-language program that is 

to perform the character input operation. 

R————————‏ — ا د 

The Options 

snum snum is the number of the slot from which you want to 
read. If snum is in the range 1 to 7, inclusive, future 
characters are read from the device in that slot. If snum 
is 0, future characters are read from the Apple II's 
keyboard. All other values of snum are invalid and must 
not be used. 


The INZ Command 
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The FRE Command 


To give access to the fast housekeeping routines that ProDOS has, 
you can use the FRE command in this form 


PEE 





For Example 


You can use the FRE command in a program in the same format as 
any disk ۵ command 


"El 


ct. Loo es E G a} "LES Sa dL La : 
HIT CHEE ررتے‎ "FRE" 


By the Way: The Applesoft command ۶۲۲۳۲ FEE cs» still works, but 


it uses the slow Applesoft housekeeping routines instead of the faster 
ProDOS routines. 
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Text in Files | 


About This Chapter 


This chapter introduces you to the use of ProDOS text files. It 
describes how to create them, how to place information in them, 
and how to take information from them. 


The first part of the chapter is an introduction to the two types of 
text files: sequential-access text files, and random-access text 
files. The next part of the chapter teaches you how to write 
programs that use sequential-access text files. The last part of the 
chapter is a description of the text file commands as used with 
sequential-access text files. 


The next chapter teaches you how to write programs that use 
random-access text files. it is a continuation of this chapter, so 
read this chapter first. 

You might use the commands described in this chapter 

e in a program that keeps a list of words for a guessing game 
e in a program that saves and retrieves text 


e in a program that saves and analyzes experimental data. 


This Chapter's Commands 


The commands in this chapter are summarized below. These are 
all the commands you need to use ProDOS text files. 


OPEN Prepare to use a file 
You must use this command before you use a text file. If the file 


mentioned does not exist, a text file is created. If the file does 
exist, OPEN checks to see that the file is a text file. 


This Chapter's Commands 
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A field is a sequence of characters that 
ends with a carriage return. 
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CLOSE Stop using a file 


Use this command to tell ProDOS that you have finished reading 
from and writing to a file. Before ending, your program must close 
all the files that it opened. 


WRITE Prepare a file for writing 


Use this command to tell ProDOS the file you want to write to and 
where in the file you want to start writing. You can use the WRITE 
command only after the file is opened; it remains in effect until you 
give the next ProDOS command. 


READ Prepare a file for reading 


Use this command to tell ProDOS the file you want to read and 
where in the file you want to start reading. You can use the READ 
command only after the file is opened; it remains in effect until you 
give the next ProDOS command. 


APPEND Prepare to write to the end of a file 


Use this command to write data starting at the end of a text file. It 
opens thé file, positions to the end of the file, and then writes to 
the file. 


FLUSH Send all unwritten data to the file 


ProDOS writes characters to files in groups, not one by one. 
FLUSH causes all characters that are not yet written to a file to be 
sent. After you use FLUSH, you can be sure that the characters in 
the file are identical to those that the program has printed. The 
CLOSE command does a FLUSH before it actually closes a file. 


POSITION Read and discard fields in a file 


This command lets you skip a specified number of fields in the text 
file before you read or write more information. 


Of These Commands: Only CLOSE and FLUSH can be used in 
immediate mode. All can be used in programs. 
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m. eee سس‎ =. eguential-Access Text Files: 
An Introduction 


You can think of a disk full of sequential-access text files as a 
collection of scrolls. Each scroll, like the sequential text file it 
models, can contain an unlimited number of lines of text. The 
analogy is appropriate because in both cases you must search 
through line by line to locate a particular line of text —there are no 

In this section, 2 scroll models a pages or markers to make the search faster. 

sequential text tile. i 
As you read these rules, bear in mind that a scroll represents a 
sequential text file, the scroli’s name represents the file's name, 
and a line on the scroll represents one line, or field, of text within 
the text file. A field is simply a string of characters that ends with a 
carriage return. There is also a pointer to keep track of your 
current position in the scroll. 


To print new lines onto a scroll, use these commands in this order: 


1. OPEN name. This selects the named scroll, opens it, and points 
the pointer to the first line. If a scroil by that name is not in the 
collection, one is created. You must use OPEN before you can 
read from or write to a scroll. 


2. WRITE name [,number of lines]. This starts at the pointer of the 
named scroll, and skips lines, one by one, until it has skipped 
number of lines. You must use WRITE before you can use PRINT 
(step 3). 


3. PRINT phrase. This places phrase on the line pointed to. Phrase 
can be a character, a number, a word, or an entire line. Phrases 
are printed one after another unless you use WRITE to select a 
new line number. PRINT destroys anything that was previously 
on the line. You can repeat this step as often as necessary. 


4. CLOSE name. This rolis the scroll back up, and returns it to the 
collection. 


Figure 6-1. Printing to a Scroll 
OPEN SCROLL 





WRITE SCROLL. 8 lines س‎ 


Skips 
to 
PRINT '....... 
PRINT ''...... یڈ‎ 
PRINT ''...... | 


CLOSE SCROLL 
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Here are the commands you use to read lines from a scroll: 


1. OPEN name. This selects the named scroll, opens it, and points 
the pointer to the first line. If a scroll by that name is not in the 
collection, one is created. You must use OPEN before you can 
read from or write to a scroll. 


2. READ name [,number of lines]. This starts at the pointer of the 
named scroll, and skips lines, one by one, until it has skipped 
number of lines. You must use READ before you can INPUT 
phrases from the scroll (step 3). 


3. INPUT phrase. This reads a phrase from the current line of the 
scroll. If there are no more phrases on the current line, it reads 
the first phrase from the next line. You can repeat this step as 
often as necessary. 


4. CLOSE name. This roils the scroll back up, and returns it to the 
collection. 


You can have up to eight scroils simultaneously open. That is why 
you must always refer to them by name. 


The phrase used with the PRINT and INPUT statements can be any 
expression or list of expressions allowed by BASIC. 


۰ 


Random-Access Text Files: An Introduction 


You can think of a disk containing random-access text files as a 
collection of notebooks. Each notebook, like the text file it models, 
has a name and an unlimited number of pages. Each of a 
notebook's pages holds the same number of characters, but since 
lines can be of differing lengths, there is no specific number of 
lines on a page. 


This analogy is appropriate because in both cases you can flip to a 
certain page before reading or writing lines of text. 


As you look through these rules, remember that a notebook 
represents a random-access text file; the notebook's name 
represents the file's name; each page in the notebook represents 
one record in the file (each record in a file holds the same number 
of characters); and a line on a page represents a field in a record. 
There is also a pointer to keep track of your current position on the 
current page of the notebook. 
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To write information on a page of a notebook, you use these 
commands in this order: 


1. OPEN name. This selects the named notebook, opens it, and 
points the pointer to the first line of the first page. If no 
notebook by that name exists, one is created. You must use 
OPEN before you can read from or write to a notebook. 


2. WRITE name [,page number] [,number of lines]. This quickly 
opens the named notebook to page number. If the page with 
that number is not yet in the notebook, that page is added to the 
notebook. If a number of lines is given, that many lines are 
skipped, one by one. You must use WRITE before you can use 
PRINT (step 3). 


3. PRINT phrase. This adds phrase to the current line on the 
current page. Phrase can be a character, a number, a word, or a 
line. Phrases are placed one after another until you use WRITE 
again, so you must be careful not to print past the end of the 
page. You can repeat this step as often as necessary. 


4. CLOSE name. This closes the named notebook and returns it to 
the collection. 


Figure 6-2. Printing to a Notebook OPEN BOOK 





PRINT "Once" 
PRINT "upon" 
PRINT "a time" 
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To read from a page in one of your notebooks, use these 
commands in the following order: 7 


1. OPEN name. This selects the named notebook, opens it, and 
points the pointer to the first line of the first page. If no 
notebook by that name exists, one is created. You must use 
OPEN before you can write to or read from a notebook. 


2. READ name (,page number] [,number of lines]. If you use page 
number, this quickly opens the named notebook to page 
number. If a number of lines is given, that many lines are 
skipped, one by one. You can next use INPUT to read from that 
page. 


3. INPUT phrase. You read each phrase from the page with an 
INPUT statement. Phrases and characters are read sequentially 
from the page until you use READ again, so you must be careful 
not to read past the end of the page. You can repeat this step as 
often as necessary. 


4. CLOSE name. This closes the named notebook and returns it to 
the collection. 


You can have up to eight notebooks open at any given time. That is 
why you must always refer to them by name. 


A random-access text file has an unlimited number of records 
(pages); each holds a fixed number of characters. Within each 
record, you can print as many fields (lines) as will fit. As mentioned 
above, a field is a string of characters that ends with a carriage 
return. 





Sequential- and Random-Access Text Files 


As the scroll analogy illustrates, you can use the information in a 
sequential-access text file in a sequential manner only, that is, 
starting at the beginning of the file and working towards the end. 
Because of this, sequential files are best suited for applications 
that read the entire contents of the file at the beginning of the 
program, and that write the modified contents back to the file at 
the end of the program. 


The records (pages of a notebook) in a random-access text file, 
however, can be used in any order; a program can modify a single 
record of the file without affecting the others. Thus random-access 
text files are best for programs that keep track of a large number 
of pieces of information that are about the same size. 
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So how do you decide which type of text file to use? It is a matter 
of preference, but you might want to consider the following 
aspects of text file use: 


Disk space: The first time you write to a record in a random- 

access text file, the entire record is placed on the disk. Thus if your 

records are each 200 characters in size, and if you write only one 
character to each of them, you are wasting 199 characters of disk 

space per record. Because records aren't usually entirely filled, 
random-access text files use up more disk space than do 

sequential text files. 


Amount of data: If you are going to read all the information into 
memory at the beginning of the program, it is faster to read it, field i 
by field, trom a sequential text file. 


Use of data: If the information won't all fit in memory, and you 
won't use it in any particular order, it is much faster to use a 
random-access text file. 


Sequential text files are best for lists of variable length 

information, such as lists of words or lines of text. In fact. many 

word processors store their text in sequential text files. Later in 

the chapter you will write programs that place text in, and read text 
7 from, sequential text files. 


Random-access text files are best for storing many pieces of 

5 information that are of the same size, and that will change 
frequently. You might use random-access files to store monthly 
inventory records, a list of names and addresses, or even a file of 
help screens (the text for each ProDOS help screen is stored in 
one record of a random-access text file). You will write a program 
that uses random-access files to keep a list of names and 
addresses. 
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Position-in-the-File Pointer 


In the scroll and notebook analogies there was a pointer that kept 
track of the current position. Every open text file has one too. As 
you read from a file, the current position is the character following 
the last character read. Likewise, when you write to a file, the 
current position becomes the spot in the file immediately following 
the last character written. When you first open a file, the pointer 
indicates the first character position in the file. 


in the rest of this manual, the position-in-the-file pointer is referred 


The current position is the character to as the current position. 
following the last read or written 
character. 
Random-Access Text Files: An introduction 
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To see a complete description of the 


text file commands and their options, 


refer to Appendix B, the summary of 
ProDOS commands. 
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Sequential Text Files 


The text file commands have many options. Because you will use a 
few of them most of the time, and most of them only once in a 
while, the commands and their options are explained by example, 
with emphasis on the most frequently used options. 


Work through the examples in the order given. Explanations of 
concepts that have already been presented will be briet. 


pO ER —— ———— nm 


The Field 


The basic unit of a sequential text file is a field. A field, like a line of 
text on the screen, is a series of characters that ends with a 
carriage return character. When you print a line to the screen using 
the BASIC statement PRINT, without a terminating semicolon, the 
line is ended with a carriage return, and the cursor goes to the next 
line. Likewise, when you print to a file using the BASIC statement 
PRINT, without a terminating semicolon, the field is terminated 
with a carriage return; subsequent printed characters go into the 
next field in the file. 


The following BASIC statement could be used to write a line to the 
screen, or a field to a text file. 


= E سا سا‎ pe 
F i om 15 


nn 


TE PRINT "THI E 


EIS 
LL mt 0 
= i" imi ا‎ 


The following tine, however, writes just part of a line to the screen, 
or part of a field to a fite; the semicolon at the end prevents a 
carriage return character from ending the current field. 


m, tio Tt 
TRT "Ti 


LE: ESI 


mr o ST ou mem: mu 
TT Fm T m ۱. ۳۳ T--H 
05 MT d سا‎ 


idt 


ان 


A subsequent PRINT statement adds characters to the same line 
on the screen, or to the same field in a text file. A sequential text 
file can contain any number of fields. 


Chapter 6: Text in Files 


c‏ سے —— سی ےا اہ ee‏ داب ات 





Character sequence: 
Field number: 


D$ is (CONTROL)-(D). 


Set the prefix to indicate the 
/EXAMPLES/DATA directory. 


Open LISTFILE: create it if it doesn't yet 
exist. 


Prepare LISTFILE for writing. 


Put the program's listing in LISTFILE; 
line 40 directs it there. 


CLOSE all open files. 


n - —- --- -= LES IMPIIS‏ ہے pet‏ سے ہم 


Storing Characters in Fields 


Here is an example that shows the way characters are stored in the 
fields of a sequential text file. Assume that you have already given 
the OPEN and WRITE commands. You can place six fields in an 
open sequential text file using these BASIC statements. 






ae FF 
E IE 
QE FE 
mi مرن‎ 
= Y rr ۲۳ 
PRP FF 
"D m 
ER CT: 
۳ ) 
ااا‎ v. 


A program would normally use the CLOSE command to close the 
file. Here is how the characters generated by lines 40 through 90 
would be stored in a file. A carriage return is represented by the 

symbol >. 


GREEN> YELLOW> ORANGE> RED> VIOLET> BLUE> 
{ FO 4 F1 Ft F2 (۳۴36 F4 (4 F5} 


This sequential text file has six fields, and contains 36 characters. 


Note the Fact: The first field in 2 sequential text file is field number 0. 





A Simple Sequential Text File 


To create a new sequential text file, use the OPEN command with a 
filename that does not yet exist. Here is a short program that 
places each of its lines in a sequential text file. 


= ا ہے و‎ m "pm EC ےہ‎ mmm orn 
= m— ppt: 1: سول‎ DE سط سوا مہ‎ 

o.‏ نے لے ٩1 È‏ ۱ الك ا H‏ :ہد :"ا ام 

x pm 5‏ ہے um‏ کر 

lis OF = CHES ^t 

am حر می‎ T ad سم‎ rome v m: رح کر‎ = =. mo. ا‎ y 
5 اج سر‎ | + PUR Lie m م‎ j ۳ mii! e e i jp i Û 
و ای سد‎ Pn 4 d سب = ابا‎ E i 1 سا‎ lapi “ete أ ۓۃ‎ | | 
E THT Df UPS p Tepe Tie 

imm lum‏ ے | أ e m^‏ مسط i‏ —- - ا ا سے ام !سے 

4 gx | esac sas ع‎ me MITT 1 ست چو‎ Fe TO I 

JRS EE Lx Bima ME Licirizc 

zu 2 2 ا‎ 

ا لے سے 2t‏ 

TTD‏ رگ bee em‏ رس کچ r‏ و 

ee PFRIHT UF CLOSE 
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EXEC command: see Chapter 8. 


This program is very simple. It opens LISTFILE (line 30), uses 
WRITE so that LISTFILE can be written to (line 40), and then gives 
the BASIC command LIST. Notice that LIST is not a ProDOS 
command, and is not preceded by a (CoNTROLJ)-(D). Because the 
WRITE command redirects output to a file, the LIST command 
places the lines of the program, one by one, into the sequential 
text file named LISTFILE , rather than on the screen. The last line 
of the program closes the file. 


Type in the program, and with the /EXAMPLES disk in a drive, type 
۴۱ 


The disk drive whirs as the text file is placed on the disk. When a 
new prompt appears on the screen, type 


AT 


iT 


SAMPLE 


-DATA 
and look for LISTFILE in the DATA directory. 


How can you check to see what is in the new file? Here's a little 
secret. The EXEC command tells your Apple li to take commands 
from a sequential text file rather than from the keyboard. When 
you type in lines of a BASIC program from the keyboard, they are 
entered as a BASIC program. Thus, if you use the EXEC commanc 
to enter lines of a program from a sequential text file, they too 
must be entered as a BASIC program. Type 


HE 


to remove the program from memory. Now type the command 


AMPLE: 


T 
1 
- 


۱1 


FILE 


m 
Lib 


mo TS ot 


EXEC 


One prompt symbol appears on the screen for each line in the 
BASIC program. When the disk stops spinning, and the prompts 
stop prompting, type 


LIST 
and you'll see that the program has reappeared in memory. The 


EXEC program is described in Chapter 8; there you will see that 
this technique of listing a program to a file is a valuable tool. 
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A carriage return is represented by the 
symbol > . 


Table 6-1. Printing to a Text File 


c‏ -—- ^ ہے يي سيو wm‏ سم 


tor سے سم‎ 0 cr 
یچ‎ ‫َ 


Writing to a File Using PRINT 


There are several ways that the PRINT command can be used to 
place characters into a text file. In the examples in Table 6-1 A$ 
has the vaiue DOG, and BS has the value CAT. 





PRINT Adds Comments 

Statement Characters 

PRINT TEXT > Completes current field. 

“TEXT” 

PRINT 

“TEXT”: TEXT Adds to current field. 

PRINT A$;B$; DOGCAT Adds to current field. 

PRINT A$,B$ DOGCAT > Unlike PRINT to the screen, 
spaces are not added 
between elements 
separated by commas. 
Compietes current field. 

PRINT DOG,CAT> Adds two elements to the 

current field, and‏ ۵ھ 


completes the fieid. See 
second example, Table 6-2. 





The exampies in Table 6-1 are intended to show three basic 
techniques: adding characters to the current field, completing the 
current field (subsequent characters will go to the next fieid), and 
adding elements to a field. 


Elements, each written and read by a single variable, are strings of 
characters that are separated by commas. They deserve special 
mention because you may need to use some special techniques to 
retrieve them intact from files. 





Reading Characters From a File 


There are several ways to read characters from a text file: INPUT is 
best for some types of data, and GET is better for others. 
Table 6-2 shows some of the ways to read characters. 
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سے کس ره الكل مہہ مسا 


Table 6-2. Reading From a Text File 


۵8 is (CONTROL)-(D). 
Set the prefix to /EXAMPLES/DATA. 


Create the file FOUR.FRUITS. if 
necessary, and OPEN it. 


Before WRITE is used, characters still 
go to the screen. 


Prepare FOUR.FRUITS for writing. 
Put field 0 in the file. 
Put field 1 in the file. 
Put fietd 2 in the file. 
Put fieid 3 in the file. 
Close FOUR.FRUITS. 


The symbol! > means {RETURN}. 





Effect 


input Statement 


INPUT A$ Reads one element of a field. If there is more 
than one element in the field, the rest of the 


field is discarded. 


Reads two elements of a field. If there are 
more than two elements in the field, the rest 
of the field is discarded. if there are not two 
elements in the field, elements are read from 
the next field. 


Reads the next character from the file. The 
GET statement reads all characters, 
including commas and colons. This is a good 
way to read fields with varying numbers of 
elements. 


a nnn 


As illustrated by the first two examples in Table 6-2, an INPUT 
statement must contain one variable for each element in a field if it 
is to read all the elements from the field. If a carriage return is read 
before characters are assigned to all variables, characters are 
automatically taken from the next field. 


INPUT A$,B$ 


GET C$ 


تس Án‏ ——————— — سس وو .- 


One Element Per Field 


Here is a program that writes four fields, each containing one 
element, to a sequential text file. 


S FEM MARE. FEIT 

i D$ = CHRE : + 

258 |PRIHT بقل‎ "FR EPI ج۔‎ ٣۳٣ >0 6۰ 
TH PRINT OF: "OREM FOUR PRIT" 

4a PEINT "THIS GOES Ta THE ZCEEEH 
sa PRINT D$; "WRITE ]لام بان‎ 
BM FEIHT "APPLE" 

Te | FEIHT "ERHHRHR 

za FEINT "CHHTBLGUFE 

SG FRINT "DRHTE" 

IMM PRINT Df;"CLOZE FOUR.FREUITZ" 


Notice that even after FOUR.FRUITS is open, you can still PRINT to 
the screen (line 40). However, after the WRITE statement in line 50, 
all PRINT statements send their characters to the file. Here is how 
the characters are stored in FOUR.FRUITS . 
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Character sequence: 
Field number: 


DS is (CONTROL)-(5). 
R$ is Carriage Return. 

Set the prefix to /EXAMPLES/DATA. 
Prepare FOUR.FRUITS for use. 
Prepare FOUR.FRUITS for reading. 


For fields O through 3, read field | from 
the file, and print it on the screen. 


Then do the next field. 
Close FOUR.FRUITS when done. 


When there are no elements left in a 
field, INPUT reads trom the next field. 


Print the four fruits on the screen, one 
fruit per line. 


D$ is (CONTROL)-(b). 


Set the pretix to /EXAMPLES/DATA. 


Create the file VERB.LIST, if necessary, 


and prepare to use it. 

Prepare to write to VERB.LIST. 
Print three elements in field O. 
Print three elements in field 1. 
Close VERB.LIST. 


- کس پر‎ ore سر اس‎ oe 


tampoco Mem ALSO > > 


APPLE> BANANA> CANTALOUPE> DATE> 


+ FO }{ F1 Ji F2 yi F3 } 


Here is a program that reads the four fields out of the sequential 
text file FOUR.FRUITS , and into successive elements of an array. 
It also prints them onto the screen so you can see that it’s working. 


5 REM GET FRUIT 

15 DF = CHEF C43 

eh FE = CHR (130 

sep PRINT D, "PREFIX . rESAMFLES DATA" 
46 PRINT U£$;"OFEH FOUR FRUITS" 

PRINT OF: ۵ FOUR, FRUITZ"‏ فاد 
eg FOR I = B TD 3‏ 

re + IHPUT ری یت‎ 

eB o: PRINT ۳۴+ 1 

SH HEST i 

ie  FRIHT OF; "CLOSE FOUR,FEUTTS" 


This program uses the INPUT statement once for each field it 
reads from the file. If you wanted to read all four fields with a single 
INPUT statement, you could replace lines 60 through 90 with: 


E IHFUT 0ں ٭ تم‎ , ASE, ASE 

ES 

za 

ap PRINT ABS RS ALE, RE. ALE. RELA SS 


The string variable R$ was set to carriage return in line 20. When it 
is printed, a carriage return is printed on the screen. 


ial 


Multiple Elements Per Field 


Here is a program that places three elements in each of two fields. 
Following it are programs that read the elements in different ways. 


5 REM CONJUGATE 

ip OF = CHET £4» 

2H PRINT D£$;"FPREFIX -EXAMPLES-ORTR" 
zB PRINT رم‎ "۱۱۳2۲ WERE LIST" 

$6 PRINT DE "WRITE VERBE, LIST" 

Se FEINT “ORINE. ORAHE, تا‎ 

gA 7م‎ TIRE Dae ۵۹ 

Te | PRIHT OC" CLOSE VMERB.LIST 


Sequential Text Files 
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ae ee سس می‎ 
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و ارت موی و وم و دون 


o M‏ وہہ 
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Character sequence: 
Field number: 


D$ is (CONTROL)-(D). 
R$ is Carriage Return. 

C$ is Comma. 

Set the pretix to /EXAMPLES/DATA. 
Prepare to use VERB.LIST. 

Prepare to read from VERB.LIST. 


Read three elements from field 0, and 
three elements from field 1. 


Print all six elements 
on two separate lines. 
Close VERB.LIST. 


D$ is (CoNTROL)-(0 ). 

R$ is Carriage Return. 

Set the prefix to ۸۰ 
Prepare to use VERB.LIST. 

Prepare to read from VERB.LIST. 
Read first element from field O. 
Read first element from field 1. 
Display the two verbs. 

Close VERB.LIST. 





. سے‎ —M — 


The commas between the verbs in lines 50 and 60 are actually 
written to the file. When an INPUT statement with multiple 
variables reads these commas, it treats them as markers for the 
end of the element currently being read. Here is the character 
sequence for the file VERB.LIST (The symbol > means (RETURN)). 


DRINK,DRANK,DRUNK-» THINK, THANK, THUNK> 
4 ۳0 i F1 } 


Here is a program that reads each verb from the file into a 
separate variable. 





= HE COM ئا ال‎ ATEN 
1 n E E 2 
b LM ۲ے اہ‎ ET 
Tam m. C تج و ور‎ 4 
ld ee = LARS 1.52 
TH T£ a sao" 

* سار ہا اسم سما‎ me, eee cutee! CTT رس وى اس جر‎ 
45 GR THT D£:"FPEEFIX -BRAMPLES-OARTA" 
T DEINHT De: UO Peep yeri ITTC 
اف سے‎ moT سے‎ P. Tm. m r- Pif"cm = aen cal 
end ابا‎ CE: "REST VERE. LIJT 
— کر و‎ nr qo Sa hc. = د سے‎ 
DES سز‎ Bis,mMzt,nzz,mAt Rts Ans 
a Od Gb وک کک‎ Nas de C mer 
ze PRINT ALE:CS Ast: C$: RSF i RS 

Ase: CP رج رج‎ REF 
2n PRINT OF: "CLOSE WERE. LIST" 
-— "o. 1 ml Û ۱ LE UM جم‎ Lum ا حا 'ے‎ i سا اس"‎ oom È 
۰ 


Notice that line 70 simply reads consecutive elements from the - 
file. When all the elements are read from one field, elements are 
automatically taken from the next. 


Line 80 prints out the elements so that they look just like they did 
in the original program. Note the use of C$ to print a comma, and 
R$ to print a carriage return. 


The next program reads only the present tense verbs. 


ot 
e 
۱ 4 


0 
— 


red‏ سد 
اس 
moa‏ 3 
دو 
Lic‏ 
RIT‏ 
w‏ 


5 
یہ 


ا ند 
d‏ ا 









J ا‎ CR رن نف‎ Pa e 1 
my 


ے 30 ٦‏ ت تب ق oD‏ 
CS‏ ید وید be‏ وید بی سر کل Aon‏ 





BF ; ۱ 
ch PEIR $i دع رج‎ 
BHO PRINT. ODUPIULLUSE VERD obeT” 
Chapter 6: Text in Files 





Data element: A string of characters 


separated by commas. 


ہے سے ریو شوہ oe me‏ ا mp‏ كس ل 


دو رت -IT-—— ——À‏ ہمہ 


In this example, as explained in Table 6-2, each INPUT statement 
causes an entire field to be read, regardiess of the number of 
elements used in the INPUT statement. Thus line 60 causes the 
string "DRINK" to be assigned to A1$, and line 70 causes the 
string “THINK” to be assigned to 825. Finally, the verbs DRINK 
and THINK are displayed. 


pr————— EEE EEE niet 


GET Characters From a File 


The INPUT statement has its limitations. It is designed to read 
data elements—strings of characters separated by commas. If 
you want to read in strings of characters that may contain 
commas, colons, or other control characters, or if you want to 
detect particular characters as they are read, you must use the 
GET statement to read the characters one by one. 


The GET statement works the same whether you are reading 
information from the keyboard or from a text file. 


You can use the GET statement to read a variable number of 
elements from a field. If you have been working through the 
examples, you have already used the program CONJUGATE to 
create the file VERB.LIST ۰ If you haven't done this, use the 
command 


irt 


EUH -ERAMPLE 


“= Te 


FF: 
and a text file named /EXAMPLES/DATA/VERB.LIST ts created. 


Although we know that there are three elements in each field of 
VERB.LIST , there are situations in which your program will not 
know how many elements to read from a field. Let’s write a 
subroutine that uses the GET statement to read any number of 
elements, separated by commas, from one field of a file. 


The following subroutine reads elements, separated by commas, 
and then places them into consecutive elements of string array AS. 
The element in use at any time is indicated by AS(I). 


The GET statement returns one character. This subroutine reads a 
character into the variable C$, and if the character is not a comma 
or a carriage return, adds it to AS(I). Because a comma separates 
two elements, the subroutine upon reading a comma adds 1 to the 
variable ۱, causing | to indicate the next element of the array, and 
then continues reading characters. It repeats this process until it 
reads a carriage return, which marks the end of the field. 


Sequentia! Text Files 


£ - ام سح Mare — - -e a wee‏ ايه 
am n‏ سی برس شيم à c9 ome ier‏ ہوا E CC XM ar ——— Ao‏ تی D a Tn -——— utu Qum noe.‏ 
2 ج سم Eh a a‏ و Paes‏ دا 8 0 





ee —— 


اك alt‏ دا و zo.‏ 


R$ is Carriage Return. 


Start with array element 0. 
Use next array element. 
Read the next character. 
If comma, use next element. 
If carriage return, you're done. 
Otherwise, add C$ to element. 


D$ is (CONTROL )-(D)). 

Set the prefix to /EXAMPLES/DATA. 
Prepare VERB.LIST for use. 

Prepare VERB.LIST for reading. 
Read all elements from a field. 
Close VERB.LIST. 


Now print the | elements of A$ onto the 
screen. 


"۹2-۲ 
EI 0 
~ 4 

0 

+ 

0 


eH R$ = CHES C122 

sus. OREM BERG H FIELD 
Lagg I = 8 

DEDE. ID EE GI 

tate GET CX 

raza IF C£ = "," THEN 
تا‎ IF C£ = kẹ THEM 
ISE FREI = AF LTS + 
idee GOTO 1029 


The next program uses this subroutine to retrieve the elements 
from the first field of the file VERB.LIST . Recall that you use a 
subroutine by saying GOSUB followed by the number of the line on 
which the subroutine starts (see line 60 below). When the RETURN 
statement in the subroutine is executed (line 1040 above), the line 
following the GOSUB statement is executed (line 70 below). 


= REM USE ZUBERUGLHITIHE 

18 OF = CHEE £4: 

34 PRINT D$; "PREFIX » 
4d PREIHT رقن‎ "OREM VER 
Sa PRINT D£;"EEAD VERE 
em GOSUE i 

)رر ھا سی زا mTLIT D‏ — 

pg FEIT UF LSE WE 
en FOR J = 1 TO I 

a : PRINT AEC. 

ل HEAT‏ ات1 

118 ENC 


To test this program, type in the lines of the program and the lines 


of the subroutine, and then type 


Rin 


You see the three words in the first field of the file VERB.LIST 





UD um T] 


سوج 
Bed‏ وس 


Į: 
-r 
sa 

rn 


Era (a 7 


p 





printed on the screen, one word per line. 


In this example only the first field was read from the file. A 
technique for reading a variable number of fields from a file is in 


the program GET. TEXT below. 
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Aliow enough room for 100 lines of text. 


Ask tor next line of text with a line 
number followed by a colon. 


Cail a subroutine that reads a line of 
characters into array element ABI). 


If AS(I) is not empty, then go to line 110, 


which prompts for the next line of text. 


Entering and Heading Text 


You are now going to write two short programs: one that reads text 
from the keyboard and then saves it to a file, and another that 
reads text from a file and then prints it on the screen. 


As you read through the following explanations of the programs, 
don't bother typing in the lines of the programs. You can find these 
programs in the /EXAMPLES/PROGRAMS/ directory as the files 
MAKE.TEXT and GET.TEXT. 





A Program for Entering Text 


This program is stored in the file 
/EXAMPLES/PROGRAMS/MAKE.TEXT . It lets you type in up to 
one hundred lines of text and save them in a file. It asks for lines of 
text, reads them from the keyboard, and places them into 
consecutive elements of the array A$. The program stops reading 
lines as soon as it encounters an empty line. This portion of the 
program is: 
iB DIM A 


ا سے i‏ 


LSB دای‎ 


i? 


a Ss 1 
uS E اس" سے سے‎ 


Poe OTF golo xl we aem GOTO 
oet at dtc a 


This part of the program uses a couple of little tricks. Since the 
value of a variable is 0 the first time it is used, the first time 
line 110 is executed, | is set to 3, and the prompt 


T: 
ad: 


is printed on the screen. Next, line 120 reads a line of text into 
array element |. Thus the Ith line of text is placed in array 
element I. If that array element is not empty—that is, if it does not 
have a length of zero—then line 130 goes to line 110, which asks 
for the next line of text. 


Entering and Reading Text 


NOE "‏ رہ مھ لی بل ھی ہی یر ہش A‏ وو کے شور a aae‏ رسب ہہ اسه پیک عرس لايد سالا aed‏ کے 24- 
— 5 و کا و اپ پاچ س ا س اا د چیپ س o my‏ سد سیم چو Pee‏ یھ 5 T————‏ نیج ~ mS‏ - : 





عو dca ps‏ ایم wm‏ تناس ہجو و 


eo‏ سی سے 


HEEE 


M ای‎ HARA هد اه‎ ~ o 
دا کی میں قد میں سے‎ HE 5 
چا‎ poii <3 x 3 وت‎ ۹ 
we Om YE Ac A" 5 





Once all the text is in the array, the program asks you for the name 
of the file in which it is to place the text: 


148 PRINT D£;"PREFIX «EM i 
154 INPUT "SERVE TO WHAT 
164 IF LEN oN? = 8 THEN £ 





and reads that name into the variable N$. Line 160 gives you a 
chance to end the program without saving the text to a file. If the 
name of the file has a length of zero—that is, if you pressed 
(RETURN)before typing any other characters—the program goes to 
line 230 which is the end of the program. (Notice the different 
techniques used by lines 160 and 130 to detect empty strings.) 


Next comes the task of saving the contents of the array to the 
named file. The last line that the program read in is line |, and it is 
an empty one (used to indicate the end of the text). Therefore, now 
print lines 1 through | - 1 to the file. Do this as follows: 


0$ is (CONTROL)-(D ). Za OCF = CHRE id? 
۱ Open the named file (N$). 178 PRINT OF; "OREN IHF 
l Prepare to write to the file. 155 PRINT OF; "WRITE INH} 
: For each line of text, 1 تاد‎ FOR J = 1 To I = 1I 
i print the line to the file feo: PRINT Agi 
۱ and continue to the next line. Zia WEST ل‎ 
Close the file when done. zz  PEIMT DF; "CLOSE "SNe - 


Finally, end the program with the line 





: ZAM TEXT ؛‎ EHD 
i 
The purpose of the TEXT command is explained below. 
If you type in the program as presented so far, it works. The à 
following lines print the instructions for using the program onto 
i the screen, and freeze them there. 
| 4& TEXT : HOME 
SH FRIHT " TE? 
لا‎ INVERSE , FRINT “TO al 
Pa HORMAL : PRIHT " E! 
RHO PRESS RETURH" 
SO | IHVERSE : FRIMT "TO 1: 
328 HORMAL + PFRIHT " PRESS FETURH IH RH 
EMPTY LINE" 
15A PRINT : FORE 24,6 
1 
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Setting the text window is discussed in 
an appendix of the Appiesoft BASIC 
Programmer’s Reference Manual. 


Allow enough room for 100 lines of text. 


Ds is (GONTAOL)-(D). 


R$ is Carriage Return. 


e‏ رم Xon e vem rm me‏ او ا ہا تھے 





Line 40 causes the Apple ۱۱ to switch the display to full screen text 

mode, to clear all characters from the screen, and to move the 

cursor to the upper-left corner of the screen. Lines 50 through 90 

place the instructions for the program on the screen, some in 

normal letters, and some in inverse letters. Line 100 freezes the 

upper six lines of the screen so they remain on the screen even if 
you enter more lines than the screen can hold. This is called i 
setting the text window. 


Run this program a few times, creating text files of different 
lengths. Experiment with the different features of the program to 
become familiar with the way they work. 


For example: You can enter a blank line of text by putting spaces on 
that line; since the line contains characters, the length of the fine is 
not ۰ 


pe——————MM——————— E —— ——  ——Á— 


A Program for Retrieving Text i 


This program is in the file /EXAMPLES/PROGRAMS/GET.TEXT . 1 
Load the program so you can look at the lines as they are 
described below. 


First the program sets up the variables it is going to use. It ۱ 
dimensions the array A$ to hold up to 100 elements, and it assigns 
the values RETURN and CONTROL-D to R$ and 05, respectively. 


ze DIM AFIR? 
38 OF = CHEE c4» 
ورك‎ R$ = OCHRE Ciz 


In line 60, the program asks for the name of the file from which it is 
to read text, and reads the filename into the variable N$. 


2۰۸/۵1 HüME 

SS PRINT OF: "PREF 2 
= m, pm tt - یچ و‎ 
el THRU "LIZT WHAT 





Entering and Reading Text 
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ہے اہو یہس epa‏ سے تم 





Open the text file. 
Prepare to read from the file. 


For each line that could be in the text 
file, 


read the line into array element | 
and then print it on the screen. 


Then do tha next line. 
Close the file. 
Restore text mode, and end. 





Having read the name of the text file, the program can now read 
consecutive lines from the file: 


inn PRINT DE; FE tHe 
T. سے سر‎ T 1 FI. Eia QERI 
11 FEIN TE: "RERD 4 
126 FOr I = 1 TO ics 
1280 : PRIWT I” i DOGUE isch 
t45 HERT I 
{Ed  FEIHT : PRINT D8; "CLOSE "HE 
i280 TERT ۲] 


There is a small probtem with this part of the program. If the text 
file contains fewer than 100 lines, the program reads the last line 
of the text file, and then has no more characters to read. The 
program tries to read a character anyway, fails, and prints out the 
error message 


To prevent this occurrence, use the ONERR GOTO statement 
described in Chapter 5. If you inciude the line 


the program, upon encountering an error, simply closes the file 
(line 160) and ends. 


Note: This is not the best way to use the ONERR GOTO statement. 
Before taking any action, a better version of this program would check 
to see which error occurred . Refer to the section on the ONERR GOTO 
statement in Chapter 5 to see how to do this. 


The subroutine that reads lines of text is, as before 


1 GET is سن سس‎ CE 

m owes pe mr ER Iu‏ + * حم جب 
iF Cf = Et THEM RETURN‏ 1 
D d c S m mae T n ۳‏ 0 ;4 
icu mil = Ase: + £X‏ 
GOTO i8‏ 1838 
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+ مد ے 


Lom جو نہد سے۔ یم سے‎ ES re qr ہے ہے۔ ہیں‎ — cit 


سے ہے سس ee‏ سو كيد - و T‏ —————— 


ewe سد‎ ow - 


Te TO V0 oc 


~- 


The lines presented so far comprise a complete program; if you 
type them in, they will run. As before, you can add a few lines that 
permanently place instructions for using the program on the 
screen. 


re PRIHT FEINT TYPE: CONTROL- 
To STOF "نا5118 ا‎ 

De ۳ ۲ AHY HEY TO COHTIHUE?" 

26 FEINT PRIAT 3 FOKE 24,5 


Line 50 causes the Apple II to switch to full screen text mode, to 
clear all characters from the screen, and to move the cursor to the 
upper-left borner of the screen. Lines 70 and 80 place instructions 
for the program on the screen. Line 90 freezes the upper six lines 
of the display so they remain on the screen even if you enter more 
fines than the screen can hold. 


The OPEN Command 


You can use the OPEN command only in deferred mode. 


Before your program can write to or read from a sequential text 
file, it must open the text file using this command 


OPEN pn [,S#] [,D#] 


Files that you open must be closed (usually at the end of the 
program). If you don’t close a file that you open and write to, you 
may lose some of the written data. 


When a program opens a text file, ProDOS designates a space in 
memory, called the file buffer, to hold all important information 
about the file, and prepares the system to read or write starting at 
the beginning of that file. Up to eight files can be open at once. 


If the file designated by pn does not yet exist, a file with that name 
is created, and is added to the proper directory. If the file exists, 
and is already open, you get the FILE Ez error. You (or the 
program) must close the file before opening it again. 


BEEN D M سس‎ 


Warning 

When you open a file, the pathname or partial pathname with which you 
opened the file becomes that file's identifier. In all subsequent references 
to that file, you must use exactly the same pn—even if you change the 


prefix, See the example which follows. 
ا ي‎ UU سیپ‎ 


The OPEN Command 


مت uo‏ ——————€ 
22 کا ےی یہ ا DTI‏ ( 3 كاك ۰ 





ےچ مہ درس ام 






PME 












f HC 0‏ 5 ر 


eT entes‏ ور زا 
Tu * 0 yk cin‏ 
eh 7 ARN‏ ا 
HEAR‏ ہے ٣ۃ‏ نے 





Pe. 


Assume the prefix is currently set to /APPLE/ (a popular fruit). ۴ 
you open the file /APPLE/STRUDEL using the BASIC line 


ri اب‎ 


n 


mf Thi 
cee te e من‎ PH 


ift 


T 


1 
i 


you must always use the name STRUDEL when referring to that 
file. For example, if you subsequently use the commands 


رس بت 





2E 





you get the File HOT © 
changed. you should still use the same file identifier: 


PER mo Tabi: i 
To» PE i 


اط ہا هم Sa‏ نے 


Dı Cı m: 


meim ۳ ۳ 
ا‎ j i 


m 


The OPEN command has other options that are not applicable to 
sequential text files. They are discussed elsewhere. 





The Options 

pn pn indicates the name of the file to be opened. If the file 
already exists, it must not be open. If the file does not yet 
exist, a file of type text (TXT) is created. 

[S&] The slot option has its usual meaning. 


[De] The drive option has its usual meaning. 





For Example 


Several examples of the OPEN command have already been 
presented. The following section explains a new aspect of OPEN. 


Delete Before Opening 


Suppose your program routinely replaces an old text file with a 

new one with the same name. If the new one is shorter than the old 
one, then unless the program deletes the old file first, the new one 
has part of the old file hanging on the end. If you don't want all this 
extra text at the end of the file, you must delete the old file before 
writing to the new one. This is usually easy, but what if it is the first 
time you have run the program, and the old file doesn't yet exist? 
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DS is (CONTROL)-(D). 


N$ is the name of the file. 


Open the file. If it does not already exist, 
it is created. 


Close the file before deleting it. 


Since the file definitely exists. the file 
can be deleted. 


For example, suppose a game creates and uses the file 
/GAMES/DINGER , and you wish your program to delete that file at 
the start of each new game. The line 


252 PR 


-r 
m.d 
PS 


if the file doesn't exist, and the program halts. Here's a quick way 
to delete a file and open it for new data, whether or not the file 
aiready exists: 


qo" rU. i — pi ۳ یں و سو‎ 

iB OF = LARS ics 

جاجح سی PT‏ حدمي ػ٣ر,ر‏ ]8 ےہ kit‏ وخ 

ak HT = Mls ms L 11 2 rr, 

an mm Tai MEG کسر سا رو‎ f و‎ 
E Pii via: rrt Hx 
EN EAE 50 5 .ے7‎ ge يد میس‎ 3 iat 
46 PRIHT OF: "Lise Hi 
> DETUT Pie, Umit: CTE RP 
De mri ۹ LS کا سا شتا گا‎ ٣۰ 


DpINT DES رز‎ 
Lig | "il : 


ii mee! | الي‎ 


The rest of the program goes here. 


Simply open and close the file before deleting it. This ensures that 
the file exists and can be deleted. 


The CLOSE Command 


You can use the CLOSE command in either immediate or deferred 
mode. 


After a program finishes writing to or reading from a file, it must 
close the file. Proper closure of every file is necessary to ensure 
that all characters are written to their files, and that the file buffers 
are properly released. CLOSE takes the form 


CLOSE [pn] 
mu" AE YES 


Warning 

A program must always close a file that it opened. [n some circumstances, 
however, a program that contains an error will stop before it can close all 
open files. When this happens, issue the CLOSE command from the 


keyboard to close all open files. 
en 


The CLOSE Command 
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The Options 


The CLOSE command without any options closes ail open files. 


[pn] pn indicates the name with which the file was opened. 


ToS ST EI) The WRITE Command 


You can use the WRITE command in deferred mode only. 


You must use the WRITE command before you can use the PRINT 
statement to place characters in a file. The WRITE command 
identifies to ProDOS the file to which you want to write characters, 
and the position in the file where the first character will be placed. 
The WRITE command remains in effect until the next ProDOS 
command is given. This command takes the form 


wea و ہے“‎ m A wo جو‎ 


WRITE pn [,F 4] [BF] 


— A — YS EE (—— ——— M— ——————— 


The Options 


Use the F# and 87 options to choose the position of the first 
character to be written to the file. If you don't use these options, 
the first character is written to the file's current position. 


pn pn indicates the name of the file to be written to. it must be 
identical to the name with which the file was opened. 


(Fz] # is the number of fields past the current position that 
ProDOS is to read and discard. ProDOS does this by 
reading characters, starting at the current position, until it 
has read the specified number of carriage returns. This 
option changes the file's current position. : 

[.B#] # is the number of bytes, or characters, that ProDOS must 

read and discard. The new current position is the sum of + 

and the previous current position. 
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T ہے‎ The READ Command 


You can use the READ command only in deferred mode. 


You must use the READ statement before you can use the INPUT 
and GET statements to read characters from a file. The READ 
command identifies to ProDOS the file from which to read 
characters and the position in the file from which to read the first 
character. The READ command remains in effect until the next 
ProDOS command is given. This command takes the form 


READ pn [,F#] [,B#] 





The Options 


Each time you use the READ command you must identify a file by 
name (pn). 


Use the Fz and B+ options to choose the position of the first 
character to read from the file. ۱۶ you don’t use these options, the 
first character is read from the file's current position. 


pn pn indicates the pathname or partial pathname of the file 
you want to read from. It must be identical to the value 
of pn with which the file was opened. 


[LFz] # is the number of fields which ProDOS is to read and 
discard. ProDOS does this by reading characters, starting 
at the current position, until it reads the specified number 
of carriage returns. This option changes the file's current 
position. 


[BZ] ٭‎ is the number of bytes, or characters, that ProDOS is to 
read and discard. The new current position is the sum of + 
and the previous current position. 


The READ Command 
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See the descriptions of the OPEN, 
POSITION, and WRITE commands for 
more information on the operation and 
use of the APPEND command. 








The APPEND Command 


Use the APPEND command only in deferred mode. 


The APPEND command lets you add data to the end of a 
sequential text file. It is like three commands in one: it opens the 
file (see the OPEN command), positions to the end of the file (see 
the POSITION command), and then writes to that file (see the 
WRITE command). This command has the form 


APPEND pn [,S#] [,04] 
After giving the APPEND command, your program can send data 
to the file using the PRINT command. 


a — —— 


The Options 


pn pn indicates the file to be appended. It must not be open. If 
the indicated file does not yet exist, the file is created. 


[S2] The slot option has its usual meaning. 


[D&] The drive option has its usual meaning. 


* 


سس سس —— — —  ——‏ ——] ال وساب لفسا ا nÉ——————Ó‏ 


For Example 
You can modify the program MAKE.TEXT—which creates a 
sequential text file—so it adds lines to the end of a text file. 


With the /EXAMPLES disk in drive 1, and with ProDOS started up, 
toad /EXAMPLES/PROGRAMS/MAKE.TEXT into memory and 
display it on the screen with the commands 


cpu 


ee 


LORD -EXRMPLE 


Do you remember how MAKE.TEXT works? First it reads lines of 
text into the array A$, then it asks you for a filename, and then it 
opens the file and prints the lines of text to the file. 
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To append lines of text to the end of a file, all you need to do is 
replace the OPEN and WRITE statements with an APPEND 
statement. Replace lines 50, 170, and 180 by entering the 
following lines: 


m,‏ ا e‏ سوا پا ہم 
حم il‏ = 
ساسا Do»‏ 





ee 2 pes s Lem ہے‎ 
اس س ۶ نس‎ s. 
EN ۶ ۳ Eu wi 


FL RAHI BEREHI 


The APPEND command, like the OPEN command, creates a new 
file if the file you try to append does not already exist. 


The FLUSH Command 


Use the FLUSH command in either immediate or deferred mode. 


As a program writes to a text file. ProDOS stores a block of 

512 bytes, or characters, of data before any of the data is placed 
on the disk. If you use the FLUSH command, all the characters that 
are currently stored are transferred to the file. After you use the 
FLUSH command, you can be sure that every character written to 
a file is actually placed in that file. The FLUSH command takes the 
form 


FLUSH [ph] 


peu a LOL e 


The Options 


The FLUSH command without any options flushes all open files. 


[pn] ہم‎ indicates the file to be flushed. It must be identical to 
the pn with which the file was opened. 


— dB — I M — íán iMi EEUU ril! 
For Example 


This command can be useful if you wanted to make a program 
absolutely foolproof. If you use the FLUSH command after each 
statement that prints to a file, you can be sure that every character 
actually reaches the file. Your programs will be a little longer and a 
little slower, but a lot more reliable. 


The FLUSH Command 
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This command is also of great value for data collection 
applications in which there are frequent power outages. If your 
application program is named STARTUP, the program will restart 
after each power outage. Using FLUSH, you can maximize the 
amount of data collected. 


Note: Frequent use of the FLUSH command slows down your program. 
You must decide the importance of speed versus data integrity. 


The POSITION Command 
Use the POSITION command in deferred mode only. 


With the POSITION command, you can access the information in 
any field or byte within a file. This command, which takes the form 


POSITION pn,F# 


starts at the current position, and reads and discards the number 
of fields mentioned in F#. The file must be open. 


For example, if the current position is within the fourth field of a 
file, and you want to read from the tenth field in the file, skip six 
fields using the POSITION command with the option ,F6. 





The Options 
pn pn indicates the file whose current position is to be altered. 
It must be identical to the pn with which the file was opened. 


F4 2 indicates the number of fields to be read and discarded. 
If you try to position past the end of the file, you get the 
EHC) OF COATS error message. 
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Random-Access Text Files 
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Random-Access Text Files 
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This chapter introduces you to the use of ProDOS random-access 
text files. It describes how to create them, how to place 
information in them, and how to take information out of them. 


Because random-access text files are so similar to sequential- 
access text files, this chapter assumes that you are already familiar 
with the material in the preceding chapter. 


The first part of this chapter explains the structure of random- 
access text files and how you can make use of it. The next part of 
the chapter leads you through a typical program that uses 
random-access text files. The remainder of the chapter contains a 
description of the commands you use to manipulate random- 
access text files. 


By the Way: Notice that although the commands described in this 
chapter are the same as those in Chapter 6, the options that 
accompany them are different. Appendix A contains a summary of the 
commands with all their options. 


Random-Access Text Files 


As illustrated by the scroll versus notebook analogy in Chapter 6, 
there is a fundamental difference between sequential and random- 
access text files: a sequential text file is a single unit, composed of 
a series of fields; a random-access text file consists of multiple 
units, or records, all the same size, each composed of a series of 
fields. Figure 7-1 illustrates this comparison. 


Random-Access Text Files 
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Figure 7-1. Sequential and Random- 
Access Text Files 


Record length is the number of 
characters a record can hold. All 
records in a single random-access text 
file are the same length. 


DER te 





Sequential Random-Access 





Record Length 


When you open a random-access text file for the first time, you 
must assign it a record length. For example, to open a random- 
access text file named /MUSIC/CLASSICAL that has a record 
length of 33, use the command 


1 


PRINT ٭ح‎ “OPEN +MUSIC“CLASSI! 


ba 


The length of a record is the number of characters it can hoid. 
Each record in the file /MUSIC/CLASSICAL is 33 characters long. 


Notice that when you open a random-access text file, you don't 
need to specify the number of records that the file is going to hold. 
ProDOS takes care of such details for you. 





Writing to a Record 


When you use the WRITE command with a random-access text file, 
you must specify the number of the record to which you are going 
to write (just like writing to a page of a notebook). If the specified 
record does not yet exist, ProDOS reserves enough space on the 
disk for that entire record. Thus, even if you are only going to place 
one character in a record of the CLASSICAL file, that record will 
use 33 characters' worth of disk space. 
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Storing characters is explained in the 
section on fields in Chapter 6. 


سای mn‏ مم م mem‏ سیر رسود سم رہ سے ge re ee ee amm‏ 


سر سے سم یسر سم ho‏ مہ a‏ سے ایک E‏ لاو جس وم کا u=‏ 


For example, before writing to record 10 of the file you just 
opened, use the command 


i1 QlTUM پا ہر جج‎ “pm. رس ےس‎ wes : ك‎ ii 
۰۰۱ ۱۱۳ DE CGMERILSCEHSSICHL- kii 


F 


SG PRINT D 


$e 


The subsequent PRINT statements you use place characters into 
record 10 of this file. 


inside a Record 


The storage of characters in a record is just like the storage of 
characters in a sequential text file. The difference is that there is a 
maximum number of characters that will fit into each record. 





Warning 

You must be careful not to print more characters to a record than it can 
hold. if you do, ProDOS simply prints the extra characters into the 
beginning of the next record. For this reason, a file's record size must be 
at least as great as the largest number of characters to be stored in any of 
its records. Don't forget that the carriage return at the end of each field is 
counted as a character too. 





E‏ ی 


Reading From a Record 


When you use the READ command with a random-access text file, 
you must specify the nurnber of the record from which you want to 
read. For example, to read the seventh record from the 
CLASSICAL file, use the command 


or m, da - “p.m Ta mr oH 
0 


PRIMT OF: "READ ISTE ۳ , ۴ 


٥ء lid‏ لل ےہ ےم L‏ 


NE 


G 
followed by the appropriate INPUT or GET statements. If the 
record does not exist, the READ statement is allowed, but the first 


re m, =, «p e, 


INPUT or GET statement causes the ENG CF UF FF error message. 


A Sample Program 


To illustrate the use of random-access text files, here is a short 
program that you can use to keep track of an address list. The 
program has two main tasks: to enter new addresses and to look 
up addresses that are already entered. Each of these two parts is a 
subroutine; a main program calls these subroutines as needed. 


A Sampie Program 
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M mom ee Re PAAR ص ےر‎ ee eee 
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Open sequential file on drive 2 in 
defauit slot. 


Open random-access file with record 
length of 100. 


Open a directory file. 


ae 


FRE 


Use the FRE command in either immediate or deferred mode. 


PRIM? CHEE (42: FRE” 


This command removes any data remaining from former programs 
from the memory area used to store your program's string 
variables; that is, it cleans house. 


Possible Error: 
uHTRE ERROR 


Text File Commands 


This section contains a brief description of each text file 
command. 





OPEN pn LL] [, Ttype] [Se] [,Dzt] 
Use the OPEN command only in deferred mode. 


Examples: 
DFEN SESAME. SEED, D2 
DFEN یات دسا انا و‎ 


3۴66۴81 OOOR, | لا‎ 


This command allocates a memory buffer to the file indicated by 
pn, S#, and D#, and prepares the system to write or read from the 
beginning of the file. If the file did not previously exist, a text file is 
created. L# specifies the file's record length; if omitted, the record 
length defaults to the record length with which the file was opened, 
or to 1 for a new file. 


Using Ttype you can open non-text files for reading and writing. 
Non-text files must be created before they can be opened. You 
must be careful when using this feature: the contents of non-text 
files can be difficult to deal with when using BASIC strings. 
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Figure 7-3. Writing an Address to 
Record Five 


E‏ — ا ery‏ چوس ہل ee‏ ہیں سور 
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Type in this program and run it. The disk drive spins as the new file 
BLACK.BOOK is created (OPEN causes a new file to be created if 
it does not already exist), and the 0 is placed in it. Then type 


HME i 


to remove this program from memory. You no longer need it. 





Writing a Record 


You must now decide how information is arranged within each 
record. Each record contains a name, an address, a city, a state, a 
zip code, and a phone number. Place each piece of information in 
a separate field; that is, use a separate print statement to place 
each piece in the record. To improve the clarity of the program, use 
a separate variable for each piece of the address. Figure 7-3 
shows the BASIC statements that place an address in record five 
of a file named BLACK.BOOK . 


PRINT D$;''OPEN BLACK.BOOK.L200" 


PRINT D$,"WRITE BLACK.BOOK.RS" 


PRINT N$ ——— ————————-| NAME 5 
PRINT A$ هس‎ | ADDRESS ^ 
PRINT C$ a | CITY> 
PRINT S$ u | STATE ^ 
PRINT Z$ سس‎ | ZIP CODE > 
PRINT سس وم‎ | PHONE > 





PRINT D$; "CLOSE BLACK.BOOK" Record 5 


To write a new record to a file 


1. Read in the new address to be entered. Store it in the variables 
N$,A$,C$,S$,Z$,P$. 


2. Add 1 to the total number of records stored (TR=TR+ 1). This 
is the number of the new record. 


. Use OPEN and WRITE to prepare that record to be written. 
. Print the new information to the file. 


. Print the new total number to record O. 


O om A O 


. Clase the file. 


A Sample Program 
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Prepare to read record 10 from 
/EXAMPLES/HELPERS. 


Skip 100 fields of the file BOOK and 
prepare to read. 


For more details on READ, see the 
section "Reading From ProDOS 
Directories," Appendix D. 


Prepare to write to start of record 29. 


Prepare to write to current position in 
file. 


Cumt ھں۔- مد‎ 
a ime ly 
4 


ra 


اميد —— س سود 








READ pn LRZ]LFZ]LB£Z] 


Use the READ command in deferred mode only. 


Examples: 
FERD «EXAMPLES HELPERS, Rie 
لاج‎ BOOK, Fla 


This command alters the current position and prepares input to be 
taken from the indicated file. If R# is used, the current file position 
is moved to the beginning of the specified record. If F# or Bz is 
used, the current position is moved forward the specified number 
of fields and bytes. 


Once this command is given, all characters asked for by INPUT or 
GET statements in the program are taken from the specified file 
starting at the file's current position. Each INPUT statement is 
ended by a carriage return character (ASCII code 13) or 224 bytes, 
whichever comes first. The READ command is terminated by the 
next ProDOS command, or by the null ProDOS command, that is, 


printing (CoNTROL)-(6). 





Warning 
Due to the limitations of BASIC strings, the reading of non-text files may 
not work as you expect it to. 


If you open and read a directory file, you get back strings that are 
identical in format to the lines returned by CATALOG. 


Possible Errors: 


+ 8 EHD OF DATA 
Il ERROR نج 8را‎ OPTION 
HOT DIRECT COMMAND P NR کر مسر‎ 
FILE HOT UFEN 





WRITE pn LRZ]LFz]LBz] 
Use the WRITE command only in deferred mode. 


Examples: 


im tT 


1۱ 7 





۳ 
p 
1۳-۳ 
pi iT, 
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Figure 7-4. Reading an Address From 
Record Five 


When you want to stop the program, press (CONTROL)-(C )and then 
press (RETURN). These keystrokes, as described in the 0 
Tutorial, stop almost any program. If you typed in lines 11-13, type 


4 
i 


12 
13 


to remove them from the program. 





Reading a Record 


You already know how information is stored in the records. Your 
new task is to find a way to ask which record (address) is to be 
displayed. To do this, display the name from each record, together 
with its record number, and then ask for the number of the desired 
address. Figure 7-4 shows the BASIC statements that read an 
address from record five of the file BLACK.BOOK . 


PRINT 0۶۱۳۴۲ BLACK.BOOK,L200" 


PRINT D$;"READ BLACK.BOOK,R5" 


NAME^ INPUT N$ 
ADDRESS INPUT A$ 
CITY> INPUT C$ 
STATE 2 INPUT S$ 
ZIP CODE 2 INPUT Z$ 
PHONE 2 INPUT P$ 





Record 5 PRINT D$;"CLOSE BLACK.BOOK" 


To read a record from the file 

. Use OPEN and READ to prepare the file to be read. 
. Read the total number of entries from the file. 

, Print a numbered list of the entries on the screen. 

. Find out which entry to display. 


. Print the selected record on the screen. 


om A OO N a‏ تن 


. Close the file. 


A Sampie Program 
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" 0 PERE: 
ا‎ Sy M s 4 wi tog 
ا می وی‎ QU کر‎ ET 


Read and discard 227 fields. 


رھ ہی یرمس t‏ 


اہ سا ET‏ — لعو ست ne‏ 


m M — ee —À 











KEBHGE ERROR iá Û 

WRITE FEUTECTEL PATH 

Ili ERROR FILE 

INVAL IO GPT Doh FILE 

HO ELFFERZ AVAILABLE iT 1 

ERREUR‏ ۲۰۳۳ بے 

FLUSH [pn] 

Use the FLUSH command in either immediate or deferred mode. 
Example: 

PLUSH wWITH-OQELIGHT 


The FLUSH command without options causes ail open files (with 
the exception of EXEC files: see EXEC) to be flushed. If pn is used, 
only the specified file is flushed. When a file is flushed, any 
characters in the output part of the file buffer are written to that 
file, and updated index and allocation buffers are copied to the 
file's directory. 


Warning 

The FLUSH command is useful for preserving the integrity of the data on a 
disk. A program that may stop unexpectedly— whether due to power 
surges or little kids—should flush its buffers frequently. This way you can 
prevent much data from being lost. 


Possible Errors: 





EREGE ۷ EEROR‏ جج۴۲ 
ERROR‏ ہد وو رج THWAL IC: OPTIGH‏ 
POSITION pn ,F#\,R#‏ 

Use the POSITION command only in deferred mode. 
Exampie: 

POSITION لانت‎ ES DATA. PETTY 


POSITION causes z fields to be read and discarded. For 
compatibility with DOS 3.3, the يع‎ and RF options are 
functionally equivalent. 


Appendix A: Summary of ProDOS 


pe AT -——— — 


Clear the screen. 

Prepare to read record R. 
Read address. 

Print name and address. 


Put city and state on the same line. 


Print zip code and phone number. 
Close the file. 

Position the cursor. 

Preserve the screen. 


D$ is (CONTROL)-(D). 


F$ is the file of addresses. 
Clear the screen. 


Convert response to number. 
If bad entry, try again. 

Enter a new address. 

Look up an address. 


o —— 2‏ سو سے تھا ےھ سی ا ہے 9—-- ےم 


The last part of this subroutine places an address on the screen. It 
uses READ to position to the requested record and uses INPUT to 
read the six fields from the record. Then it prints the six fields on 
the screen. Line 2230 prevents the address from being erased 
before you have a chance to read it. 


2158 HOME 

2168 PRINT Gf: "READ ";Ff;".R";FR 

و ھی ا  IHPLUT‏ تا ات 

FRINT HE: FRIHT A$‏ ادا ات 

2140 FRIHT Cf, FEINT SF 

esse PRINT £4: FRIHT FE 

Saige FRIHT OF; "CLOSE "Fg 

zzza VTRE 22: HTRB & 

Z236  IHPUT "PRESS RETUEH TO COHTIMUE': Tt 
2z48 ۳۶۹ 


Controlling the Program 


The remainder of the program is simple. Here is the main part of 
the program that lets you choose between entering a new address, 
reading an existing address, or ending. 


ig OF = CHEE رون‎ 

2B FR = "wEMAMPLES “DATA BLACE BOOK" 

zB HONE 

4p FRIMT "WHAT WOULO YOU LIKE TO DOF": ۴۲ 
So FRIMT " 1 ENTER A NEW ADDRESS" 

PRIHT " 2 LOOK UF AH ADDRESS"‏ ترم 

7 PRINT " 3 EHD": 7م‎ 

IHPUT "TYPE & HUMBER AHD PRESS RETURN "Cg‏ جح 
aû ۶ = WAL ٩‏ 

ipa IF C < 1 üR C > 3 THEH GOTO zB 

118 IF C = 1 THEH SITE 8 

izG IF C s = THEN GOSUE 8 

1 219 IF C = 2 THEM EHD 

148 GOTO zB 


Lines 80 through 100 use the same technique that you used earlier 
to choose a record to be displayed. They read in a letter, convert it 
to a number, and then check to see that the number falls in the 
expected range. If it is a bad entry, the program repeats the 
question. A good entry causes the proper subroutine to be called. 


See if you can modify the program to delete and change entries. 


A Sample Program 


- سوا‎ —- wx mmi coo ovy om RA er comam 08 


- D- c 
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eee‏ کو و و 


Figure 7-2. Five Addresses in the File 


Record 
Number 


5 


The first address you give the program is stored in record one of 
the file, the second in record two, and so on. The total number of 
records in the file is stored in record zero of the file. Figure 7-2 
represents the structure of the file when it contains five addresses. 








Joe's Mama 


D — الل‎ ————— 
2 ——————— Addresses 


۹ مہ۱ تسس ہ ہہسسس سس‎ 9 | 2911 Main St. 


D$ is (CONTROL)-(0). 
Open the file, 

Write to record 0. 

Put a 0 there. 

Close ail files. 











(8 of them) 






Bill Smith 


Los Altos, CA 





Total Number of Addresses 


The total number of addresses in the file is initially O. First write 
and run a little program that places the initial total number in 
record Q. 





S 3EM 7 
id G$ = CHE 

28 PRINT OF 

28 PRINT OF 

ig PRIMT B 

PRINT D£;"CLÜSE"‏ ج5 


Line 20 opens the file BLACK.BOOK, in which addresses are to be 
kept, with a record length of 200. Thus, addresses stored by the 
program can have no more that 200 characters in them. Line 30 
specifies that data will be written to record 0 of the file. Line 40 
prints a 0 to that record, and line 50 closes the file. 
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o^ ee 


حا اس و ےچ 


حم سلجي 


Warning 

Be sure that a file's record length is greater than the maximum number of 
characters that you will ever put in one of the file's records. If you 
accidentally write past the end of a record, data is written onto the 
beginning of the next record in the file, destroying any data that might be 
in that next record. 





[S4] The slot option has its usual meaning. 


[Di] The drive option has its usual meaning. 


The CLOSE Command 


Use the CLOSE command in either immediate or deferred mode. 


After a program finishes writing to or reading from a file, it must 
close the file. Proper closure of every file is necessary to ensure 
that all characters are written to their files, and that the file buffers 
are properly released. CLOSE takes the form 


CLOSE [pn] 


EN a سسسوععووسسسسسے ں‎ 


Warning . 

A program must always close a file that it opened. In some circumstances, 
however, a program contains an error and stops before it can close all 
open files. When this happens, issue the CLOSE command from the 


keyboard to close all open files. 
es 


وه ا QUSS‏ 


The Options 


The CLOSE command without any options closes all open files. 


[pn] pn indicates the name of the file to be closed. It must be 
identical to the name with which you opened the file. 


The CLOSE Command 


vro vom c cuim رم‎ m £o نے‎ o سوہ ہو یو‎ c Momo 8 7 عد‎ oo cO ہے‎ 





M ee!‏ و ہیے۔ 





+ مهم همهم 





Read name to be entered. 
Read address. 

Read city. 

Read state. 

Read zip code. 

Read phone number. 


Open the file with record length of 200. 


Read totai records. 
Get total records; add ۰ 
Prepare to write to record number TR. 


Place each part of address in a 
separate field. 


Prepare to write record number in 
record ۰ 


Print new record number. 
Close the file. 
End of subroutine. 


Store records in file 
/EXAMPLES/DATA/BLACK.BOOK. 


Call the subroutine, over and over 
again. 





Here is a subroutine that does this. Lines 1010 through 1060 
gather the information for an address. 










Lag REM AO HEM INFü 

1810  IHPUT “HAME: (HE 
Wee INPUT "741 ‘AF 
ASE IHPUT "CITY: 0$ 
itd  IHPUT "STATE: "19s 
تاد لا[‎  IHFUT "ZIP CODE: "2f 
ragg INPUT "PHONE "PS 


Lines 1070 through 1120 open the file whose name is stored in F$ 
and write information to a new record (record TR) in that file. 


10TG PRINT رعق‎ "OREM ۱ LIOA" 

FRINT D: "READ ۲:۳ "Ro"‏ وا 

tam INPUT ۲8۱۲8 = TR + i 

1100 PRINT Sf: "WRITE رر‎ FS)". 8") 78 1 
1118 بجع‎ H$: PRINT Af: PRINT C£ 

11 لیات‎ FRINT 26: FRIHT Z$: PRINT F$ 


Lines 1130 through 1160 print to record 0 the total number of 
address records that are now in the file, close the file, and end the 
subroutine. 


1138 PRINT GS" HEITE res Ra” 
lide PRINT TF 

11536 PRINT GF: CLOSE =$ 

11۳8 RETURN 


These lines are already typed in and stored as part of the program 
in the file /EXAMPLES/PROGRAMS/ADDRESS . If you want to 
test just this subroutine, load 
/EXAMPLES/PROGRAMS/ADDRESS , and add the lines 


44 سم‎ we سس ال کر سک ری‎ METE رس‎ Du Zu 
ad Et = “E داح انس‎ OUR DRA OLA oS, 
ھا رس ےس رس‎ ڑ٤‎ EC! ee اب اپ کے‎ 
i lilii نا ای ز‎ 
1 وو رک کرد حر‎ 
s i db x L 
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"m mo o هد سر وہ‎ 


v3 


TU meg 


سے ہا اھ 


nnn 


The End of File 


Each file listed by the CATALOG command has a number under 
the EHCIF ILE heading. For all types of files except random- 
access, this number indicates the number of bytes in the file. For 
random-access files, this number represents the number of bytes 
that would be in the file if every record, from 0 to the highest 
numbered record written to, were used. 


For example, assume that a random-access text file has a record 
length of 50, and that data is written to records 0, 156, 756, 

and 1890. This file has data stored in four blocks on the disk. 
However, EHDF ILE is calculated by multiplying the total possible 
number of records by the record length (1891 * 50 — 94550). This 
number is used by ProDOS to determine the location on the disk 
of the last record in the file— needed, for example, if you want to 
append a record to the file. 


The READ Command 


Use the READ command only in deferred mode. 


Before you can read from a record, you must use the READ 
command to indicate the number of the record you want to read. 


This command takes the form 
READ pn [,R#] [,Fst] [,B 4] 


When used with random-access text files, the READ command 
tells ProDOS the file from which the next INPUT or GET statements 
will take characters (pn), the record within the file from which 
characters are to be read (Rz), and the position within the record 
from which the first character is to be read (F# and Bx). The READ 
command remains in effect until the next ProDOS command is 
given. 


The READ Command 


7 اك‎ anea AR ہے ا‎ RI n mM e s com um mmm سم مھا‎ Fer Sey pe سے‎ 


ee‏ لك باد ده 


س بم سسا 





Open the file. 

Read from record 0. 

Get the number of records. 
Check for no records. 
Clear the screen. 


For each record |, position to record |, 
and read the stored name. 


Print the record number and the name 
on the screen. 


Repeat for all records. 


———— P 


Empty ProDOS command; turns off 
۱ READ. 


| Get numeric value ot answer. 
۹ 
{ if bad number, try again. 


72 
۳ 





Here is a subroutine that does all these things. First it reads the 
total number of addresses from record 0 of the file. Then it reads 
the name from each address and prints ail of them on the screen. 


2088 PRINT OF; "OPER “Fe: "Lene" 

“aia PRINT OF: "REROQ "Fpi" mE" = 
لیات ات‎ THPUT TE 

IF TE = 8 THEN GOTO zzi8‏ لاو ات 

2848 HOME ١ 
ZASA PRINT “WHOSE ADORESS DO VOU ÀRHT? "i ۲ 

zaga Fur I = i TO TE 

"READ ":Ff;".R':Í‏ ریں0 PRINT‏ آا قات 

azg : IHFLUT H$ 

EMSA | PRINT I,H$ = 
2156 HEAT I 


Because the READ statement causes ProDOS to read characters 

from the file rather than from the keyboard, you must cancel the 

READ statement's action before reading anything from the 

keyboard. A READ or a WRITE is canceled by a ProDOS 

command; one way of doing this is by using the empty ProDOS 
command in line 2110 below. pa 


Line 2120 asks for a number and then reads it into the string R$. 
Since the question asks for a numeric answer, it could have read 
the answer into a regular variable, but then the accidental pressing 
of a letter key would cause an error. Line 2130 converts R$ to a 
number (R), and the next line compares the number to the valid 
address numbers. An invalid response causes the question to be 
redispiayed. 





2118 PRINT Of: PRINT 

21280  IHFUT "TYFE A NUMBER AND PRESS RETURN ie} 

zizB R = WAL CRE: 

gid IF E i i OR F TE THEN GOTO fifa DG 
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The Options 


pn pn indicates the file to be appended. tt must be open. Hf the 
indicated file does not yet exist, it is created. 


[.L#}] # indicates the length of the file's records. If z is the same 
as the record length assigned when the file was created, 
the next character written is the first character following 
the last record in the file. If not, see the following 
description. 


First ProDOS positions to the last character in the file (the 
character indicated in the EHLi- ILE column in a 
CATALOG). It divides 2۳4 ILE by the record length; the 
remainder is the offset into the current record. Finally it 
uses EHDF ILE to find the position of the first character in 
the next record (EHZIF ILE - Offset + Record 

Length + 1). Thus, if you use a record length of 1 when 
appending to a random-access text file, the next character 


the same as appending a sequential text file. 
[Sz] The slot option has its usual meaning. 


[Da] The drive option has its usual meaning. 


س 


For Example 


You can change the ADDRESS program so it uses APPEND in the 
subroutine that writes new records. 


With the /EXAMPLES disk in drive 1, and with ProDOS started up, 
set the prefix to the /EXAMPLES/DATA/ directory 


TM E ا ا ہر‎ zT 


: km im? 


5 B. 
B j 


۴۱1 


T.U. 
یز اس‎ 
1 1 


m 


Now load ADDRESS into memory and display part of it on the 
screen with the command 


bem 


m qm =. = me, wr, T, كام “م ا‎ tos 
mri FS Ope ۱ پا‎ rede PAH: 
IIT ee e E Ile. f la | E 
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۲ 
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۱ 
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The APPEND Command 
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The OPEN Command 


Use the OPEN command in deferred mode only. 


Before a program can write to or read from a random-access text 
file, it must open the text file using this command 


OPEN مم‎ [,L4] LS#] [O&] 


When you open a random-access text file for the first time, you 
must open it with the length option, L#. # is the number of bytes, 
or characters, that each record can hold. Each subsequent time 
you open the file, the original record length is assumed. 


If you open a random-access text file with a record length other 
than that with which it was created, the new record length is used 
as long as the file is open, but the original record length remains as 
the default. 


Files that are opened must be closed, usually at the end of the 
program. If you don't close a file that you open and write to, you 
may lose some of the written data. 


When a program opens a text file, ProDOS designates a space in 
memory, called the file buffer, to hold ail important information 

about the file. It also prepares the system to read c: write starting 
at the beginning of the file. Up to eight files can be open at a time. 





Warning 
ProDOS uses the name with which you opened the file as the file's 
identifier. Always use the exact same name, even if you change the prefix. 








The Options 


pn pn indicates the name of the file to be opened. !f the file 
already exists, it must not be open. If the file does not yet 
exist, it is created as a text file. 


[L4] You must use the length option the first time you open the 
file, that is, when the file is created. If you create a file 
without the length option, the file is given a record length of 
one. The record length, +, must be in the range 1 to 65535. 
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The FLUSH Command 


Use the FLUSH command in either immediate or deferred mode. 


As a program writes to a text file, ProDOS stores a block of 

512 bytes, or characters, of data before any of the data is placed 
on the disk. If you use the FLUSH command, all the characters that 
are currently stored are transferred to the file. After you use the 
FLUSH command, you can be sure that every character written to 
a file is actually placed in that file. The FLUSH command takes the 
form 


FLUSH [pn] 

—————————— سح 
The Options‏ 

The FLUSH command without any options flushes all open files. 


[pn] pn indicates the file to be flushed. It must be identical to the 
name with which the file was opened. 


The POSITION Command 


Use the POSITION command only in deferred mode. 


When used with random-access text files, the POSITION 
command works exactly as it does with sequential text files. You 
can use it to skip fields within the current record; you cannot use it 
to position to another record. This command takes the form 


POSITION pn [,F 4] Bs] 

Starting at the current position, ProDOS reads and discards the 
number of fields specified in F#, then it reads and discards the 

number of fields specified in B#. The file must be open. 

For example, if the current position is within the fourth field of a 


record, and you want to read from the tenth field in that record, 
skip six fields using the POSITION command with the option ,F6. 


The POSITION Command 
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The WRITE Command 


Use the WRITE command only in deferred mode. 


You must use the WRITE statement before you can use the PRINT 
statement to place characters in a record of a random-access file. 
The WRITE command tells ProDOS the file, the number of the 
record, and the position within the record of the first character to 
be written. The WRITE command remains in effect until another 
ProDOS command is given. This command takes the form 


WRITE pn [,R#] [,F#] [,8#] 
You must use the WRITE command each time you want to write to 


a record other than the current record. If you use the WRITE 
command without the R# option, ProDOS defaults to record 0. 





The Options 


pn pn indicates the file to be written to. It must be identícal to 
the name with which the file was opened. 


{,R#] # is the number of the record to which characters are to be 
sent. If this option is omitted, record 0 is assumed. The 
maximum record number is 16 megabytes divided by the 
file's record length, or 65535, whichever is smaller. 


If # is larger than any previous record number, the 
EHDFILE column in the catalog changes. Refer to the 
section on the End of File for more details. 


LF&] # is the number of fields that ProDOS is to read and 
discard. ProDOS does this by reading characters, starting 
at the current position, until it has read the specified 
number of carriage returns. This option changes the file's 
current position. 


[Bx] # is the number of bytes, or characters, that ProDOS is to 
read and discard. This new current position is the sum of + 
and the previous current position. 
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The Options 


pn pn indicates the name of the file to be read. It must be 
identical to the name with which you opened the file. 


LR&] ۶ is the number of the record from which you are going to 
read. If you don't use this option, record 0 is assumed. 
If R# indicates a record that doesn't exist, you don't get an 
error; the first INPUT or GET statement from a non-existent 
record causes an error. The maximum allowable record 
number is 16 megabytes divided by the record length 
or 65535, whichever is smaller. 


LF4] # is the number of fields past the beginning of the 
indicated record which ProDOS is to read and discard. 
ProDOS does this by reading characters, starting at the 
current position, until it has read the specified number of 
carriage returns. This option changes the file's current 
position. 


[B2] # is the number of bytes, or characters, that ProDOS is to 
read and discard. The new current position is the sum of # 
and the previous current position. 


The APPEND Command 


Use the APPEND command in deferred mode only. 


You can use the APPEND command to add data to the end of a 
random-access text file. It is like three commands in one: it opens 
the file, positions to the beginning of the record that follows the 
last record in the file, then it writes to that file. This command has 
the form 


APPEND pn [,L4] [,S4] [,Dz] 


After giving the APPEND command, your program can send data 
to the file using the PRINT command. 
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TMT TTT TT TT About This Chapter 


This chapter explains how you can use the EXEC command to l 
cause the Appie II to take its commands from a sequential text file 1 
rather than from the keyboard. This sequential text file can contain 
ProDOS commands, lines of BASIC program, or even fines of input ; 
to a BASIC program— nearly any command that you can type from 

the keyboard. 1 


Because the various uses of EXEC are not always obvious, 
examples are given to show how the EXEC command can be used. : 
This chapter provides several diverse examples; this may give you 
some ideas for using it in new and different ways. 


Throughout this chapter, a text file that is to be used with the EXEC 
command is called an EXEC file, and the contents of an EXEC file 
are called an EXEC program. 


Because EXEC files are externally identical to all other text files, 
you'll find it useful to place the ending .EXEC on all EXEC 
filenames. This convention is used throughout this chapter. 

You can use an EXEC file 

e to give automatically a frequently used set of commands 


€ to use instead of repeatedly typing the same inputs into a 
program 


e to combine BASIC programs or subroutines 


e to put a machine-language routine in a BASIC program. 


About This Chapter 
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Open the file with record length of 200. 


Read total records. 
Get total records; add 1. 
Prapare to write to record number TR. 


Place each part of address in a 
separate field. 


Prepare to write record number in 
record 0. 


Print new record number. 
Close the file. 
End of subroutine. 


Add after last record. 


Delete these lines. 


Put new address at end. 


Place each part of address ina 
separate field. 


Read total records. 
Get total records; add 1. 


Prepare to write record number in 
record Q. 


Print new record number. 
Close the file. 
End of subrouti 
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You now see these lines: 


tare PEINT ۷ ۱ "CFE ";F£.".Lzgg" 

{ASH PRINT D£$;"REERDU "FE" RA” 

19525  IHFUT TEITE = TR + i 

1183 PRINT OF: "WRITE "FFE" RITE 7 
1 1 1 لو‎  FRIHT HE: FREIHT AF: FEIHT CS 

1 لا‎  FRIHMT 22: PRINT :چات‎ PRIHT F 

Lice PRI! رن‎ ۱ TS PIRR," RE" 

lida PRINT TR 

1158 PRINT Of: "CLOSE "iF 

RETURN‏ تپ ت11 


The purpose of lines 1070 through 1100 is to discover the number 
of the last record, and to prepare to write to it. The APPEND 


command does just that. Replace those four lines with - 
Aara PRINT OF: "APPEHD Fes". Lege" 
1 


d pod سم‎ db 
r 
ad d 
t ۰ 
سیم‎ 
E فا‎ ١ 


is 
1 


bh l 
۲ ۳ 
را یا‎ 
x 
با‎ 


After the ‘subroutine writes the new address to the record = 
(lines 1110 and 1120), it saves the new number of records in 

record 0 of the file. Before the program can do this it must - 
discover the total number of records, as was previously done in 7 


lines 1080 and 1090. Just place the same two lines somewhere 
between 1120 and 1130 (say, 1124 and 1126), as shown below, 
and the revision of the subroutine is complete. it should now look 
like this: 


PRINT Of: "APPEWO"' Fp; Lee"‏ لا ت! 

1110 PRINT HE: PRINT AS: PRINT C£ 

11 ای‎ PRIM? S4: PRINT Z$, -PR IAT PE 

lied PRINT ر یح‎ READ "| “رع‎ ee" ~ 
lize JIHPUT ٢۴: ٣۴م‎ = TA + j 

1130 FRINT OF: "WRITE "F$" Ra" 

tide PRINT TE 

ممح" Se.‏ رعم ۶۲ ام 1156 

{ism  RETURH - 
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Press (SPACE). The screen goes blank, the message 


ATINS ZHOHOFF, ESEC 


۳1 


F: 


appears on the screen, and the disk drive's 1H USE light glows as 
the program writes the SHOWOFF file onto the disk. When the 
program finishes, you see this message 


IT'S DONE!!! 


ERHUY To انت‎ LITTLE 
a" T 


AVE TO OO IS TYF 


m 0 


m 
m 
(C1 


EXEC -;EXRMFLEZ.FREÜUOGERHMZI-ZHOHÜDFF, 


DEI 


HE RETLUREH KEY, AHE EHJdOT, 


OM, EY THE WAY. IF YOU WAHT TO SEE THE 
COMMANDS IH THE FILE 2۳۳۳, USE 
RET. TEST FROM CARPIER S TAFE 

RHH GET, TEST 
AMC HHEH IT RISES FOR A FILEHRME, JUST 
TYFE IH 


Before you actually run the EXEC program, take a look at 
SHOWOFF.EXEC using the GET.TEXT program trom Chapter 6. 


Type 
FUR GET. TEST 


then choose the file SHOWOFF.EXEC . Notice the wide variety of 
commands, that can all be typed from the keyboard. Set this 
command file into action by typing 


WPROGRAMS sHüWZ*FF,EXEC 


HII 


EXEC ~ESRMPLE: 


As SHOWOFF.EXEC is running, it describes everything it is doing. 
Surprised? Don’t be, showoffs are hardly ever modest. 
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The Options 


pn 


FÉ 


[B+] 


pn indicates the file whose position is to be altered. 


# indicates the number of fields to be read and discarded. 


If you try to position past the end of the file, you get the 
EHD oF OATH error message. 


After skipping the number of fields specified by the field 
option, ProDOS reads and discards the number of bytes, 
or characters, specified by # in the byte option. 
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DS is (CONTROL). (5). 


Set the prefix. 


Prepare the file to be written to. 


Put these four commands into the 


EXEC file DOIT. 


Close the file. 
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< REM MBKE.DDIT 

D = CHEF i43‏ جا 

"PREPIN EXAMPLES “PROGRAMS!‏ روح PRINT‏ جج 
"OPEN ] EXEC"‏ وع PRINT‏ 20 

44 PRINT C$; "WRITE 001." 

Sa PRINT "PREFIX EXAMPLES <PROGRAMS." 


کر جا سر ہو سا 
ا ۲ 


A PRIM] NIE 

“ب كل أ هر mm Tur S HIPH‏ ہے 

RLM EHIM AWAY ۳‏ لام 

s PRINT "LISZT" 

am PRINT Ge: "CLOSE DOIT, EXEC" 


After you have MAKE.DOIT and AWAY both saved in the 
/EXAMPLES/PROGRAMS directory, type the command 
RUM MARE. DOIT 

to create the sequential text file named DOIT.EXEC . To see the 


contents of DOIT.EXEC , you can once again use the program 
GET. TEXT. 


Now type the command 


pm P. 
EEG. 
سا‎ ۲ | mm ‘m 


HATT BV 
رر سا زد اج ا اتا‎ 


m 


to cause the commands in the file DOIT.EXEC to be executed one 
by one, just as if you were typing them—very quickly—trom the 
keyboard. This EXEC program displays the files in the 
/EXAMPLES/PROGRAMS directory, which should include the files 
MAKE.DOIT , DOIT.EXEC , and AWAY ; it displays the sentences 
printed out by AWAY; and finaily it displays a listing of the program 
AWAY. 
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An All-Purpose EXEC Maker Program 


Just as you can use GET.TEXT to look at an EXEC program, you 

can use the program MAKE.TEXT to create one. The only problem 
with this program is if you enter an erroneous line, there is no way 
to change it. Just make sure each line is correct before you press 


(RETURN). 


Create an EXEC File Using BASIC 
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is (CONTROL)-(B).‏ وہ 

Set the prefix. 

Open, close, and delete 
deletes POKER.EXEC 
even if it didn't exist. 

Open POKER.EXEC. 

Prepare to write to it. 

First line number of program. 

For each memory location, 
increment counter. 

Put 10 POKES on each line. 

For first POKE on a line, 

print the line number, 


then increment line number. 


Poke a byte. 

Do next location. 

New line for ProDOS command. 
Then close POKER.EXEC. 

Ail done. 


Use EXEC to Combine Programs 


Executing (EXEC) a file does not delete the program that is already 
in memory. Therefore, if you have a program in memory, and you 
EXEC a file that was created using CAPTURE, the lines from the 
text file program are added to the lines that are already in memory. 
This is a good way to combine programs or subroutines. 


سس سس سس سس سسسب را سس او ل n—— —ü)fMáw—‏ 


Machine Language to BASIC 


Here’s a program that reads (PEEKs) consecutive bytes of a 
machine-language program, and for each byte places a POKE 
statement into an EXEC program (POKER.EXEC). When the EXEC 
program is run, a BASIC program containing these POKE 
statements is entered into memory. You can use EXEC to place 
these lines into an existing BASIC program, or you can use EXEC 
to put them into memory when no other program is present and 
save it as a separate BASIC program. 
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Listing a BASIC Program to a File 
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This chapter first gives you a demonstration of the EXEC 
command, then a few different ways to create EXEC files, and 
finally some sample applications of the EXEC command. The 
section that describes the EXEC command in detail is at the end of 
the chapter. 


EXEC Demonstration 


There are two steps to the EXEC demonstration. In the first step 
you run a BASIC program that creates an EXEC file, and in the 
second step you use the EXEC command to tell your Apple Il to 
take its commands from the EXEC file. 


With your /EXAMPLES disk in drive 1, set the prefix by typing 
DESRMFL 


E. 
— ° 


PROGRAMS - 


to see this page of instructions 


* £4. EREC DEMOMSTRAT TOM 


THIS PROGRAM CREATES A SEQUENTIAL TEXT 
FILE HAMED “SHOWOPF. EXEC". EACH STRING 
THAT IS PLACED IN SHOMOFF. EMEC EY THIS 
PROGRAM 13 A LEGAL APPLE II COMMAND 
WHEH ‘oll TYFE 


THE C2 IH THE FILE SHUMOFP EMEC 
TAKE ام‎ MF CUR COMPLTER, EACH 
cCüMMRHHE IS EXECUTED JUST AS IF IT HAD 
GEEN TYPED IM FROM THE EETEUREG, 
"ERSTE FEGGERMMIHG WITH FEO 
IEZCEIEEZ THE FROGRAM IH MORE DETAIL, 
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`“ TJ Create an EXEC File Using BASIC 
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A BASIC program that creates an EXEC file must 
1. Use the OPEN command to open the text file. 


2. Use the WRITE or APPEND command to prepare the file to be 
written to. 


3. Use the PRINT or LIST command to place commands in the text 
file. 


4. Then use the CLOSE command to close the text file. 





Printing the Commands to the File 


Here is a step by step example that illustrates how to create an 
EXEC file named DOIT.EXEC that contains these commands 


FEREFIX “~ESAMPLES PROGRAMS 
CRT 

RLM AWRY 

LIST 


First enter and use the SAVE command to save an Applesoft 
program ‘called /EXAMPLES/PROGRAMS/AWAY to be run by the 
EXEC program. 


REN HM‏ بج 

18 FRIHT “A WRY TO JOURNEY, " 
za FEINT "A WHALER JME," 

z0 FRIHT "RHEIGH THE RHCHÜüR," 
44 PRIHT "AWRY WE GO,” 


Next write and save the following program, called MAKE.DOIT , 
which, when run, creates a text file called 
/EXAMPLES/PROGRAMS/DOIT.EXEC . The PRINT statements 
that begin with D$ are ProDOS commands; they are executed 
when the program is run. The other PRINT statements are written 
to the EXEC fiie, to be used later. Notice that ProDOS commands 
in an EXEC file, such as FH AMA’, should not be preceded by a 


(CONTROL)-(B). 
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The BRUN command: see aiso the 
DASH command, Chapter 4. 
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Binary Files 


About This Chapter 


This chapter describes the ProDOS commands that let you use 
binary programs and binary files on your disks. If you want only to 
run binary programs that are already on your disks, refer to the 
DASH (-) command in Chapter 4. This command moves any type 
of program from a disk file into memory and then starts it running. 


The commands in this chapter can be used 


e to load, run, and save binary programs 


© to use binary programs to read and write characters. 


This chapter also explains about system files and programs that 
are written in machine language. The end of this chapter has a 
section on ProDOS and the Monitor, and another section that 
explains how you can connect ProDOS to a clock/calendar chip so 
that files can be dated. 


This Chapter’s Commands 

This chapter’s commands are summarized below. 

BRUN Run a binary program from a file 

Use this command to transfer binary data from a binary disk file 
(type BIN) to a specified portion of memory; the program then 
executes automatically. 

BLOAD Read binary data from a file 

Use this commande to transfer binary data from any disk file to a 


specified portion of memory. Binary data is typically a machine- 
language program or a picture for one of the graphics screens. 


This Chapter’s Commands 
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Listing a BASIC Program to a File 


A far more useful application of the EXEC command is to capture 
the listing of a BASIC program as a text file. Such a program can 
be used 


e to edit a program using a word processor 

€ to place part of a program anywhere in another program 

e to insert subroutines from a subroutine file into a program 

€ to connect two programs. 

The following version of the CAPTURE program captures 

lines 2270 through 5130 of the program that is currently in 
memory in a text file named LISTING.EXEC. Replace the line 
numbers in line 5 of the program with the lines that you want to 


save, and replace the filename LISTING.EXEC with the name of the 
file in which you want the listing saved. 


i FEM CAPTURE 

D$ is (CONTROL)-(D). تج‎ UF = CHR C45 

Prepare to write to the file 3 PRIWT OF: "OPEM LISTING, EXEC" 
| LISTING.EXEC. 
4 PRINT DE ‘WRITE LISTING. EXEC" : 
i t سے وس سے وم لا‎ um — ہس‎ 
List the lines to the file. Sq LIST تام ا رتا کت‎ 

Close the file. & FEINT OF LOSE LISTING, EXEC" 

End the program. v ENC 


To use this program, you must already have a program in memory. 
Add these lines to those of the program in memory. ۱۴۲ your 
program begins with line 10, you can add these lines with the same 
line numbers; alternately, you can change the line numbers so that 
they are all greater than the highest numbered line in your 
program. 


If you placed CAPTURE at the beginning of your program, run it by 
typing 


fu iL: ہے‎ 3 
lif Poy Bp ame PME ل‎ Ys 
BESTEE L کا از نے‎ phased 


where linenum is the number of CAPTURE's first line. 
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Figure 9-2. PR# and IN# 


PRz: Send data using 
your output routine. 


PRINT PRINT 





ب رہہ ہے ہہ ———* 





D سس ہے‎ M 


. INŽ: Get data using 
your input routine. 





*Memory arrangement is arbitrary. 
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Binary Files‏ .ےس سس سس مت 

ProDOS allows you to store on disk, and retrieve from disk, the r 
information in your Apple II's memory. You have already seen the 

ProDOS commands RUN, LOAD, and SAVE: these commands deal 

with the contents of the BASIC program memory, interpreted as 

BASIC programs. The ProDOS commands discussed in the next 

three sections —BRUN, BLOAD, and BSAVE— perform similar 

functions, but they deal with the information in any part of the 

Apple ۱۱5 memory, in its uninterpreted form. 


Binary Files 


-—pe Ma. 01 ۔ میس ہا‎ RR emm ا چ‎ mo ھے۔‎ 5 m —— —— — م0‎ 
d E E BES Og یلم ہے‎ me rest rem MM پا‎ agg gag, ب‎ o e o میم میج .د‎ 











arre Be 


To use this program, put the proper memory locations in line 90, 
change the line number in line 80 if you wish, and then run it. It 
creates the EXEC program POKER.EXEC (in the prefix directory). 
Next type 


EROT piss IW 
سا‎ L| "^ nu 1 اط‎ 


Ft. سا‎ ~i 


01 


n 


and the lines containing the pokes are added to whatever BASIC 
lines are already in memory. 


The EXEC Command 


Use the EXEC command to take commands or data (all non-file 
input) from a sequential text file instead of the Keyboard. It has the 
form 


EXEC pn [F£] [, S] LD#] 
The F# option allows you to skip the first + lines of the text file. 


The EXEC program currently in memory is not affected by the 
NEW command or the CLOSE command. An EXEC program 
cannot be stopped by (CoNTROL)-(C). If an EXEC program uses the 
EXEC command to call another EXEC program, the second 
program replaces the first. 


If an EXEC program runs a BASIC program, and the BASIC 
program contains a (non-file) INPUT statement, that input request 
is satisfied by data from the EXEC file. !f you interrupt a running 
BASIC progam with (CONTROL)-(c), the remainder of the EXEC 
program usually is not executed. 


Monitor commands cannot be executed from within EXEC 
programs. 





The Options 
pn pn indicates the file containing the EXEC program. 


is the number of fields to skip at the beginning of the‏ # ۴۶ء 
EXEC file.‏ 


[,S#] The slot option has its usual meaning. 


[,D#] The drive option has its usual meaning. 
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۱ For example, if you want to save high-resolution graphics screen 1 

in a file, you must save the information that is in memory locations 

8192 through 16383 ($2000 through $3FFF). Thus, to specify the 

start address, you can give the address option in decimal or 

hexadecimal 

H2192 or ,Hfs$zhüsg 

and you can give the address of the last byte to be transferred 

using the end address option, as in 

;ETSSBS or geese er 

Alternately, if you like subtraction, you can use the length option to 

give the number of bytes to be transferred, as in 

or . Leshan‏ ج12 نا 

You can calculate the value for the length option by subtracting the 

start address from the end address and adding one. 

The relationship between these three options for high-resolution 

graphics screen 1 is shown in Figure 9-3. 

Figure 9-3. Memory Address Options Memory Address ١ Memory 
o AÑ, Ex, and Lë 

Ex: 16383 (S3FFF) End Address 
Hi-Res Graphics Screen 1 | 

L#: 8182 ($2000) Length 
جا‎ (length) = Ex - Ax + 1 | 

A#: 8192 ($2000) Start Address 

0 ($0000) 
Binary Addresses 
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The Options 


pn pn must indicate a binary file (type BIN). If you use 
only this option, the entire contents of the binary file 
indicated by pn are placed into memory starting at 
the address from which they were transferred using 
BSAVE. 


You can see the address from which a file was 
transferred by BSAVE if you use the CATALOG 
command. This address is given, in hexadecimal, in 
the column labeled 212 1 FE, and it has an Ain 
front of it. 


[At] # is the memory address into which the first byte of 
the program is to be transferred. It is not useful to 
use an address that is greater than the maximum 
memory address of your Apple Il. 


[.Bz] # is the number of the first byte in the file to be 
transferred. If you don't use this option, the first byte 
transferred is the first byte in the file, byte 0 ($0000). 


[LLz!,Ex] To load and run a portion of a file, use one of these 
options. L& is the number of bytes to be transferred; 
Ex is the last memory address into which the 
program is to be transferred. If you include both of 
these options, the last in the list is used. 


[,S:4] The slot option has its usual meaning. 


[Dz] The drive option has its usual meaning. 


سےتبنےےصحصےحح-صص--ص-ص-س-فپٹسووصصسٗ“۲۰٦۰؟سسم‎ —- 
For Example 

With ProDOS started up, and the /EXAMPLES disk in drive 1, run 
the binary program /EXAMPLES/PROGRAMS/SURPRISE using 
the command 


اود وعم 


1 
£1) 


mri 


BRUM -;EXRMPL 


Now try running it using the address option 


“PROGRAMS SURPRIS 


EK 
31 
3 


ERLH EXAMPLE! 
im 1-18 1 Lal Ama) ؟: 3 ظط‎ — be 


The BRUN Command 
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nod 
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BSAVE Save binary data in a file 


Use this command to transfer binary data from a specified portion 
of memory to any type of file. Data anywhere in the 5 
memory can be transferred to a file. 


Figure 9-1. BRUN, BLOAD, and BSAVE 


BLOAD 


BRUN: BLOADs 
a file, then runs 
the loaded program 





BSAVE 





PR# Use a binary program to print characters 


You use this command most often to send output to a device in a 
slot. You can also use it so a binary program is used in place of the 
normal character output routine. 


—— — — ee ee ee ہے ایت‎ 


۱ IN# Use a binary program to read characters 


You use this command most often to read characters from a 
device in a slot. You can also use it so a binary program is used in 
place of the normai character input routine. - 
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D$ is (CONTROL)-(D). 
Display Page 1. 

Load picture. 

Restore text. 


To clear the graphics page: see the 
section “High-Resolution Graphics 
With ProDOS." 


Token: an encoded element that 
represents a BASIC keyword. 


dd RP 


type is the three-letter abbreviation that indicates the 
type of file to be transferred. If no type is specified, 
the file must be of type BIN. 


[,Ttype] 


To transfer a portion of a file into memory, use one of 
these options. L# is the number of bytes to be 
transferred. E# is the last memory address into which 
the data are to be transferred. You cannot use both 
these options in the same command. 


].81,8[ 


[,S#] The slot option has its usual meaning. 


[Ds] The drive option has its usual meaning. 


aa — 1. LV AL "—————— ———————— Á— — 
For Example 


With ProDOS started up, and the /EXAMPLES disk in drive 1, set 
the prefix to /EXAMPLES/DATA using the command 


m: . rere 


y j سر سک‎ i me 2 iT 1 


PR 


m 


Now display high-resolution Page 1 and load in a picture by typing 
and running this program: 


۰ 


1 لا‎ OF = CHEF دك‎ 

eB HIE 

iB PRINT ر0‎ ۳6۱۱۳۵ PICTURE A2132 Lee 
4# GET A$ TEST 


To display text again (and to clear the graphics page), simply press 


(RETURN). 


LEE سس‎ ——— ———s 


Using BLOAD With Non-Binary Files 


When ProDOS places information in a file, the command that you 
use to save the information determines the format of the 
information in the file. For example, a BASIC program is saved as 
a set of BASIC tokens. 


To see how a file is stored, and to work with the file in its 
uninterpreted form, use the BLOAD command with the Ttype 
option. For example, instead of manually changing every instance 
of a variable in a BASIC program, write a program that does it for 
you. Let the program use the BLOAD command to bring a BASIC 
program into memory, change all references to the variable, then 
save the program back to its BASIC file using BSAVE (with Ttype). 


The BLOAD Command 
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The DASH command: see Chapter 4. 
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The 8 before the commands BRUN, BLOAD, and BSAVE, stands 
for binary. Each command transfers binary information, zero-for- 
zero, and one-for-one, between memory and a file. From now on 
these commands are called the binary commands. The 
information that the binary commands transfer is often a machine- 
language program or a high-resolution picture from one: of the 
Apple II's graphics screens, but it can be any information that is in 
memory or on a disk. 


The two most common uses of the binary commands are: running 
binary programs, and bringing binary images into memory for 
display. You can run a binary program using the DASH (-) 
command. ۶ا‎ you have a file that contains a binary picture, you can 
move it to the graphics page from which it was transferred by the 
BSAVE command without having to understand the memory 
addresses involved. If you want to do this, use the example in the 
section on the BLOAD command. 


Binary Addresses 


If you are going to be using the binary commands only to run 
machine-language programs that already exist, you don't have to 
understand the organization of the Apple ۱۳5 memory. If, however, 
you want to save a graphics screen to a file, or if you want to work 
directly with the binary information in memory or in a file, you need 
to know a little about memory addresses. 


Your Apple ۱۱۳5 memory is a continuous sequence of memory 
locations, or bytes, each having an address. The address of the 
first memory location is 0 (written as $0000 in hexadecimal), the 
address of the second memory location is 1 ($0001), and so on. If 
your Apple !ا‎ has 64K of memory, the address of the last memory 
location is 65535 (SFFFF). 





The Memory Address Options—[,AzZ]LEZ]L LZ] 


When you use a binary command to save binary information, you 
must give the address of the first memory location that contains 
information to be saved. The starting memory address is 
determined by the address option, Az. 


You must also give the number of memory iocations to be saved. 
You can do this using the length option, LF, which is the number of 
memory locations, or bytes, to be saved; or you can do it using the 
end address option, E#, the address of the last memory location 
to be saved. 
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The BSAVE Command 


^ To transfer binary information from your Apple ۱۳5 memory to a 
disk file, use the command 


BSAVE pn ,A# ,L#!,E# [,B#] [, Ttype] [,S#] [,04] 


You can transfer information from any part of memory (the ۱ 
A#, L#, and E# options) to any type of file (the Ttype option), ۱ 
starting at any position in the file (the 8+ option). 
You can use the BSAVE command 
e to transfer a machine-language program from memory to a file 
e to move a picture from a graphics screen to a file 
e to move any portion of memory into any type of file. 

ا ب سد تف SS‏ 1 
The Options‏ 


When you use this command, you must use the pn, A#, and either 
- the L# or the E# options. 


pn Unless you use the Ttype option, pn must indicate a 
binary file. If you use Ttype, pn can indicate any type of 
file. 

QAS You must use this option every time you use the BSAVE 


command. A# is the memory address from which the 
first byte of data is to be transferred. 


,L*|,Es You must use one of these two options every time you 
use the BSAVE command. Lz is the number of bytes of 
memory to be transferred. Ez is the last memory 
address from which data are to be transferred. 


[Bs] B+ indicates the first byte in the file to which data is to 
be transferred. If you don't use this option, the first 
byte is transferred to the first byte in the file, 
byte 0 ($0000). 

[. Ttype] type is the three-letter abbreviation that indicates the 
type of file to be transferred. If no type is specified, the 
file must be of type BIN. 

[S2] The siot option has its usual meaning. 

{,D#] The drive option has its usual meaning. 


The BSAVE Command 
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See Chapter 4 for the DASH command. 
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The File Position Option—[,Bz] 


If you don't want to start the transfer of information with the first 
byte in a file, you can use the byte option, B=, to indicate the 
number of the first byte to be transferred. 


For example, if you have two high-resolution pictures in a binary 
file, the first picture starts at byte 0 ($0000) in the file, and the 
second picture starts at byte 8192 ($2000) in the file. To address 
the second picture in the file, use the byte option 


If you use the byte option, you must also use the length option, L=, 
or end option, Ez, to specify the number of bytes to be 
transferred. If you don’t, the entire file is transferred. 


The BRUN Command 


To run a binary program that is stored in a binary disk file 
(type BIN), use the command 


BRUN pn , AS], Bs] [L7 Eg] [[S#] [D] 

When ProDOS sees this command, it transfers the file indicated by 
pn into memory, as determined by the options, and then runs the 
program. If the Az option is not used, the program is placed in 
memory starting at the address from which it was transferred 
using BSAVE. 


Warning 

ProDOS cannot teil the difference between a binary program and binary 
data such as a picture file. If you give names to binary files that indicate 
their contents, such as adding .PIC to the end of all picture files, it is less 
likely that you will accidentally run a non-program file. If you ever run a 
non-program file, parts of ProDOS might change; if this happens. it is a 
good idea to restart ProDOS. 


You can also run a binary program using the DASH command. 
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Ree... The PR# and IN% Commands 
In addition to setting up the Apple II to do input or output with a 
Refer to the Apple // or Apple lie slot, the PR# and IN# commands are also used to send characters 
Reference Manual tor more details to a machine-language program. The entire syntax of these 


about accessory-card ROM space. ۲ 
commands is 


PR# snum [,A#] or PR# Ax | 
IN# snum or INF As 


in which the option can either be the slot number (snum), the slot 
number followed by the address of the routine to be associated 
with that slot (Az), or just the address of a routine to be used (Az). 


For example, if a character output routine is stored starting at 
memory location $300, you can use this command to activate the 
routine for subsequent output: 


Output routine at location $300. FER AE Te 


The first byte of the routine starting at location $300 must be a 
6502 CLD instruction (216, $08). When you want to stop using this 
routine, you can use this command to restore output to the 

= console: 


Restore output to console, FRH i 


In addition, this same output routine can be associated with siot 2 
using this command: 


تناد 2ت = FER‏ 

Subsequent references to siot 2 are actually directed to the 
routine at $300. To restore slot 2 to normal operation, use the 
command 


FER 2, ACIOA 


Use this form of the PR# command to remap physical slots from 

one slot number to another. For example, if you have printers in 

siots 1 and 2, and a program that expects the printer to be in 

slot 1, you can use the printer in siot 2 with your program by using 
- the command 


Assign slot 2 to slot 1. FEE ز‎ APCS 


before running the program. 


The PR# and INg Commands 
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Moving a binary image of any type of 
file into memory is discussed in the 
section "Using BLOAD With Non- 
Binary Files." 


The BLOAD Command 
To transfer binary information from a disk file to your Apple ٥ 
memory, use the command 


BLOAD pn (, A2] LB#] [,L#! ,E#] | Ttype] [Se] [Du] 


You can transfer information from any file type (the Ttype option), 
starting at any position in the file (the B# option), to any part of the 
Apple tl’s memory (the Ax, ا‎ and E# options). 

You can use the BLOAD command 

e to transfer a machine-language program from a file to memory 
€ to move a picture from a file to a graphics screen 

e to move the binary image of any type of file into memory. 

If you plan to write programs that use machine-language routines 
or high-resolution pictures, you need to take special precautions. 


The sections ‘High-Resolution Graphics With ProDOS" and 
"Installing Machine-Language Routines” address these issues. 





The Options 


If you give this command using only the filename option, the file 
indicated by pn must be a binary file (type BIN). The entire 
contents of this file are placed into memory starting at the address 
from which it was transferred by BSAVE. 


pn Uniess you use the Ttype option, pn must indicate a 
binary file. If you use Ttype, pn can indicate any type 
of file. If you use the BLOAD command to transfer a 
non-binary file into memory, you must use the 
A# option. 


[Ax] & is the memory address into which the first byte of 
the binary data is to be transferred. You must use this 
option if you use BLOAD to load a non-binary file. If 
you use the BLOAD command to load a binary file 
without this option, the file is placed in memory 
starting at the address from which it was transferred 
by BSAVE. 


[Ba] + is the number of the first byte in the file to be 


transferred. If you don't use this option, the first byte 
transferred is the first byte in the file, byte 0 ($0000). 
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and all subsequent output will be sent by the routine at 

location $300. This routine jumps into the normal character output 
routine, so characters are printed in their normal fashion. Type a 
few lines of BASIC, such as 


mm TRI TT ار راو‎ p رس سر‎ Opes PT يه‎ corpse 
FEINT ii HOT LOORE Shy DIFFEREHT' 


ITI 
31ا‎ 


Tip 
LL 


and you see that characters are indeed printed on the screen. 





What PR# and IN# Really Do 


This section explains the way the Apple Ii normally sends and 
receives characters; thus you will see how PR# and IN# work, The 
Apple ۱۱ has two memory locations, named CSWH and CSWL, in 
which it stores the memory address of the routine that outputs 
characters. Together, these locations are called the monitor 
output link—they link the monitor to an output routine. tt also has 
two memory locations, named KSWH and KSWL, in which it stores 
the memory address of the routine that inputs characters. These 
are called the monitor input link. 


The monitor output link normally contains the address of the 
Apple ۱۳۵ standard output routine, COUT1; the monitor input link 
normally contains the address of the Apple II's standard input 
routine, KEYIN. These two routines send characters to the screen 
and read them from the keyboard, respectively. When you use 
PR: or IN# from BASIC, without ProDOS, the monitor links are 
set to indicate the ROM on the card in the indicated slot (SCn00 
for slot n). Thus, when the Apple ۱۱ inputs or outputs a character, it 
calis the input or output routine in the card's ROM to perform the 
transfer. 


While ProDOS is running, the monitor ۱/۵ links, instead of 
containing the addresses of the standard input and output 
routines, contain the addresses of the ProDOS input and output 
routines. ProDOS keeps the addresses of the standard input and 
output routines in the ProDOS input and output links. As you might 
expect, the ProDOS input and output links normaily contain the 
addresses of the Apple II's standard input and output routines, 
KEYIN and COUT 1. 


The PR and INg Commands 
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Refer to the Appíesoft BASIC 
Programmer's Reference Manual to see 
how to use HIMEM and LOMEM to 
protect the graphics page. 


Refer to the ProDOS Technical 
Reference Manual for more details on 
machine language. 





High-Resolution Graphics With ProDOS 


ProDOS does not ever prevent BASIC programs from overlapping 
the high-resolution graphics pages. To use high-resolution 
graphics Page 1 for graphics, use the HGR command; to use high- 
resolution Page 2 for graphics, use the HGR2 command. 





Warning 
On an Apple lle, you cannot BLOAD data into high-resolution graphics 
page 2 while 80-column text is being displayed. 





When you finish using the graphics pages, use the TEXT 
command: the BASIC program moves back down into place. When 
you use the TEXT command, the contents of the graphics pages 
are lost. 


By the Way: If you want to go from high-resolution mode to text mode 
and back again without affecting the contents of the graphics pages, 
use the POKEs described in an appendix of the Applesoft BASIC 
Programmer's Reference Manual. 





Warning 
If your program haits--—-due to a STOP statement, an error, or a 


(GONTROL)-(C (۱۷۵6۵ from the keyboard—while you are using HGR or 
HGR2, do not attempt to continue the program using the CONT 
command. Type the CLOSE command, and run the program again. 





Installing Machine-Language Routines 


Because of the way ProDOS uses memory, it is difficuit to predict 
which parts of memory are free to hold machine-language 
routines. 


When ProDOS opens a file, it moves HIMEM down 1K and places a 
1K file buffer where HIMEM used to be. It then marks that 
1024-byte portion of memory as used in the system bit map. 


To place a routine in memory, you must do the same thing: move 
HIMEM down by a multiple of 256 bytes, transfer the routine by 
using BLOAD, and then mark the used portions in the system bit 


ap. 


3 





Warning 

You must do this before any files are opened. This ensures that ProDOS 
places all file buffers below your routine, so your routine won't be closed 
instead of a file. 
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Figure 9-4. ProDOS Date and Time 
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Re-enter BASIC by pressing 


(CONTROL)-(C} 


and then pressing (RETURN). 


Using a Clock/Calendar Card 


Each time you update a file, ProDOS performs a JSR (jump 
subroutine) to memory location 48902 ($BF06). This is the entry 
into the DATETIME routine. If there is no DATETIME routine 
installed, there is an RTS in this location. 


If, however, ProDOS sees a Thunderclock in one of the slots, it sets 
up a routine and places a jump into the routine for you. If you want 
to use another type of clock/calendar card with ProDOS, you have 
to write your own routine, and place it in memory each time you 
start up ProDOS. 


The routine must read the date and time from the card and place 
this data in bytes 49040 through 49043 (SBF90 through SBF93) 
using the following format: 


49041 (SBF91) 49040 ($BF90) 
7 65 4 3 2 10 7 6 5 4 3 2 10 
Date year | month | day 
7 6 5 4 3 2 1 7 6 5 43 2 1 
Time | hour minute 
49043 ($BF93) 49042 ($BF92) 


A jump to the starting address of the routine must be stored in the 
entry to the DATETIME routine )48902( ۰ 


By the Way: The TIME program described in Appendix 0 does not 
change the time indicated by a clock/calendar card. It merely changes 
the system date and time locations described above. 
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Turn on Page 1. 
Load PICTURE. 
Save PICTURE. 


BLOAD the systern program starting 


at 8192. 
Create a new system file. 


BSAVE the data from 8192 to the 
ENDFILE shown by CATALOG. 


BLOAD the BASIC.SYSTEM file. 
Create a new system file. 
BSAVE the data. 








For Example 


This example loads a picture into graphics Page 1 and then saves 
it back into the same file. With ProDOS started up and the 
/EXAMPLES disk in drive 1, set the prefix using the command 


FEEFIX ;EXRMPLEZ.URTR 


Now, load the picture into high-resolution Page 1 and then save it 
using these commands 


ak: 


2 i 


GE 
E MAC li l EF 
BzHVUE E LETUPE HISA, L31232 
As a slightly more sophisticated example, here is how to move the 
files 280005 and BASIC.SYSTEM from one disk to another using 
BLOAD and BSAVE. Assume that you are transferring the files 
from the volume /EXAMPLES to the volume /NEW.BOOT. 


First type CATALOG «EXRMPLES to see how long the two files 
are. This is just part of the first two lines of a sample catalog: 


Egi oC 


lS i SNCF see N‏ .اب دو 


a 
=3 

3 
1 1 








]زا اعم 

CREATE 

۴ع 

BLOAD .EXHMPLESZ.E 

CREATE HEN, BOOT. 

EZALE «HEM, EDT E E 


The start address, A8192, was chosen arbitrarily. 


Warning 
Beware, however—-this process destroys anything that was in the region 
of memory into which the BLOAD command placed the data. 
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Warning 
PR# and IN# are both ProDOS commands. When used from within a 


program, they must be preceded by a (CONTROL)-{D). Failure to do so 
causes the commands to be ignored. 





The Options 


snum snum can have any value from 0 to 7. If snum is 0. normal 
input or output to the console (keyboard and screen) is 
restored. If snum is from 1 to 7, the Apple I| does 
subsequent input or output operations with the device in 
that siot. 


AR # is the address of the routine that you want to use as the 
character input or output routine. The first byte of the input 
or output routine must be a 6502 CLD instruction. 





For Example 


The first instruction of the input or output routine to be used must 
be a 6502 CLD instruction. As an example, put a two-line output 
routine starting at memory location $300. It consists of a jump to 
the normal Monitor output routine, located at memory 


د caps‏ مرت کے 


address $FOFO. 
With ProDOS started up. enter the Monitor with the command 
۱ 
1 
! 
: and type 
0300: CLD BBG; DS 40 FD FD 


0301: JMP SFDFO 
Now re-enter BASIC by pressing 


Continue BASIC, CONTROL)-(C) 


: and then pressing (RETURN). Enter the ProDOS command 


Output routine at $300. FER EE 


Lnd 
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184 OPEN 
185 CLOSE 
186 READ 
186 WRITE 
187 APPEND 
188 FLUSH 


188 POSITION 
189 The EXEC Command 


189 EXEC 

190 Binary Commands 
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When you use PR# or IN# with a slot number, ProDOS replaces 
the contents of the proper ProDOS link with the address of the 
ROM on the card in the indicated slot ($Cn00 for slot n). When you 
use PR# or IN# with an address, ProDOS simply places that 
address in the proper ProDOS link. When the Apple ۱۱ tries to 
output or input a character, the monitor output or input links 
indicate the proper ProDOS routine, then the ProDOS routine 
does a two-stage transfer: 


1. it moves the addresses of the current ۱/۵ routines from the 
ProDOS ۱۸۵ links to the monitor 1/0 links. Then ProDOS calis 
the Apple Il's normal ۱/۵ routines which use the current 
routines to perform the transfer. 


2. ProDOS reconnects itself by placing the addresses of its 
۱/۵ routines into the monitor 1/0 links. 


Not only does ProDOS have input and output links for normal ۰ 
it also has them for each of the slots. When you use the PR or 
IN# command with snum and Az, the specified address is placed 
in the links for that address. 


ProDOS and the Monitor 


If you like to play around with the Apple II's internals, you 
occasionally find yourself (intentionally or otherwise) in the 
Monitor. The Monitor is the program within the Apple {i's Read 
Only Memory that controls many of the Apple ۱۱۳5 vital functions. 


First, to enter the Monitor from BASIC, type 


BEL. 154 

and you see the monitor prompt 

$ 

All ProDOS commands still work from within the Monitor. For 


example, type 


and you see a normal catalog displayed on the screen. Likewise, 
the PR# command still starts up a disk from the Monitor. An error 
in a ProDOS command issued from the Monitor returns control to 


BASIC. 
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Summary of ProDOS 


Features of ProDOS 


Here is a list of some of the features of the ProDOS machine- 
language interface. These features are fully discussed in the 
ProDOS Technical Reference Manual. They are the basis upon 
which ProDOS is built. 


A directory-based filing system 


Up to 51 files in a volume directory; the number of files in other 
directories is limited only by space on the disk 


Up to 32 megabytes per volume 

Up to 16 megabytes per file 

20 different file types (ten of them user-defined) 

Up to eight files can be open at a time 

A defined, usable machine-language interface 

A defined interrupt protocol 

File structures compatible with Apple lII SOS 

Fast transfer rate—reads about 8K per second from Disk Il 


Supports all Apple ۱۱ disk devices 


An understanding of these features is not essential to the 
summary of ProDOS that follows. 


Features of ProDOS 
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System Programs 


By now you have undoubtedly wondered why ProDOS is divided 
into two files--PRODOS and BASIC.SYSTEM—and what the 
relationship is between these two files. 


The file PRODOS contains the most essential parts of ProDOS: 
routines that perform communication with disk drives in a 
compact and versatile way. The BASIC.SYSTEM file contains 
routines that let you communicate with disk drives through BASIC 
programs. When you use ProDOS BASIC, both these files are in 
memory and in use. 


It is possible for other assembly-language programs to make use 
of the versatile routines in the PRODOS fiie without the overhead 
of having the BASIC.SYSTEM file in memory. Such programs are 
known as system programs. ProDOS BASIC, the ProOOS Filer, 
and the DOS-ProDOS Conversion Program are all system 
programs. 


You can recognize a system program by its file type, SYS, 
displayed by the CAT or CATALOG command. Every system 
program provides some way to switch from itself to another 
system program. From ProDOS BASIC, you run another system 
program using the DASH (-) command. From other system 
programs, you usually switch to another system program by using ~- 
the Quit command. 


a  )-)--)-)-)--) ب بج‎ 


Starting Up a System Program 


When a disk starts up, the PRODOS file is first loaded into 
memory. Next a system program is loaded into memory. Then 
ProDOS scans the disk for the first file having the name 
XXX.SYSTEM (XXX can be combinations of letters and numbers 
that form a valid ProDOS filename). If it finds such a file, it loads it 
into memory and runs it. Otherwise it loads the first file of type SYS 
on the disk and runs it. 


If there is no program of type SYS on the disk, an error message is 
displayed. 
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Table A-1. ProDOS Command Options 


For the partial pathnames listed above to indicate valid files, the 
prefix should be set to /EMPLOYEES/, 
/EMPLOYEES/MARKETING/, and /SPORTS/FOOTBALL/, 
respectively. The maximum length for a prefix is 64 characters. 
You set the prefix using the PREFIX command. 


Syntax 


The syntax, or structure, of each ProDOS command is a command 
word followed by a list of options, as in 


SAVE pn [,S#] LD#] 


The command word (SAVE in this example) is followed by a list of 
options. Unbracketed options must be included each time the 
command is used. Options in square brackets, [ and], are 
optional, and can be used in any order. Options separated by a 
vertical bar are alternates: use one or the other, not both (if both 
are entered, ProDOS uses the second in the list). 


Uppercase letters and commas indicate characters that must be 
typed as shown; lowercase letters and the number symbol, #, 
stand for items that you supply. 


Table A-1isa summary of the command options. The next section 
contains a description of each of the options. 


cr A بے سے‎ — d 


Name Syntax Minimum Maximum Examples 
Pathname pn t 3 /DISK/RECORDS/JAN 
Slot Number Ss 1 7 $1 ,S3 
Drive Number Dx 1 2 Dt .D2 
Number of Fields Fs 0 65535 2 F10 
Record Number „RE 0 . ,R59 ,R3982 
Number of Bytes Br 0 i .B2 7ھ‎ 
Address in RAM At 0 65535 2 ,A4096 
Length in Bytes LG 1 65535 ۵ .L16384 
End Address in RAM „E£ 1 65535 76 ,E32768 
At Line Number QE 0 65535 .@10 322 
Stot Number snum 0 7 1 3 

File Type 5 ,Ttype 0 0 TDIR STXT 


* See the description below 
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Record Number. Used with the READ and WRITE 
commands for random-access text files. + defaults to 0 
after OPEN. Thereafter, it defaults to the last record 
specified. # points to an absolute record within a 
random-access file. The maximum record number is 
16 megabytes divided by the file’s record length, 

or 65535, whichever is smaller. 


Number of Bytes. # defaults to 0. 2 indicates a position 
in a file whose position is # bytes ahead of the current 
position. For READ and WRITE it is evaluated after the 
,F# option, and the maximum byte number is record 
length minus one. If it indicates a position past the end 
of record or file, the position is left at the end of the 
record or file, and the EHC OF CATA error message is 
returned. 


For BRUN, BLOAD, and BSAVE, it is always used 
relative to the beginning of the file. If it indicates a 
position past the end of the file, the RANGE ۳۴ 
error message is returned. 


Address in RAM. For BRUN, BLOAD, and BSAVE, 

# indicates a starting memory address for the transfer 
of binary information. If BLOAD does not specify this 
parameter, the vaiue of A# defaults to that used when 
the binary file was transferred using the BSAVE 
command. For PR# and IN#, # specifies the memory 
address of a machine-language driver routine. # must 
be in the range 0 through 65535. 


Length in Bytes. # defaults to 1. In the OPEN and 
APPEND commands with random-access files, ,L# is 
required and specifies the record length in bytes. When 
used with the BRUN, BLOAD, and BSAVE commands, 
& specifies the number of bytes to be transferred 
between the Apple II's memory and a file. # must be in 
the range 0 through 65535. With the binary commands 
,E# can be used instead of ,L#. 


End Address in RAM. This is an alternative to the 

,L& option for BRUN, BLOAD, and BSAVE. # indicates 
the last memory address for the transfer of binary data. 
Either ,L# or ,Ez is required for BSAVE. If neither is 
used with BRUN or BSAVE, bytes are transferred until 
the end of the file. # must be in the range 

0 through 65535. 
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D$ is set to (CONTROL)-(D)}. 
Print the command preceded by 


(CONTROL)-(D). 


Null ProDOS command. 


D$ is (CONTROL)}-(0). 
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List files in named directory. 
List files in prefix directory. 


List files in volume directory of slot 6, 


drive 1. 


ProDOS Commands in Programs 


You can give all ProDOS commands from within programs, and 
you can issue all except OPEN, WRITE, READ, APPEND, and 
POSITION from the keyboard. If any ProDOS command in a 
program is to be printed, it must be preceded by a printed 
(CoNTROL)-(D), and the (CONTROL)-(0)must be the first character on 
the printed tine. Here is the most common way of printing a 
ProDOS command preceded by a (CONTROL)-(D). 


CHEE 4 2 


7m FRIHT DS; "PROODGSCOMMAHO" 


me i 


“Ls 


The WRITE, READ, and APPEND commands are terminated by the 
next ProDOS command given. If you want to terminate one of 
these commands without using a ProDOS command, you can use 
the null ProDOS command 


KT 


Filing Commands 


This section contains a brief description of each ProDOS filing 
command. ; 





CATALOG and CAT [pn] LS#] [D#] 


Use the CATALOG and CAT commands in either immediate or 
deferred mode. 


Examples: 


‘AT ,.SHURTRHBHSE.-PFHÜTOUFILES 


The CAT and CATALOG commands display a list of the files in the 
directory indicated by pn, S#, and D#. If pn is not used, a catalog 
of the prefix directory is displayed uniess the prefix is empty or 
Sz or D# is used. In these cases the volume name indicated by 
S# and Dz is used instead of the prefix. 


CAT displays a 40-column list containing the first five items 


explained below, while CATALOG displays an 80-column list with 
all eight items. 
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Filenames 


A ProDOS filename is up to 15 characters long. It can contain 
uppercase and lowercase letters (A-Z), digits (0-9), and periods (.), 
and it must begin with a letter. Lowercase letters are automatically 
converted to uppercase. 


A filename must be unique within its directory. Some examples are 


ANGLOFILE 
BALLOON 
LETTER.TEXT 


Pathnames 5 


A 20005 pathname is a series of filenames, each preceded by a 
stash (/). The first filename in a pathname is the name of a volume 
directory. Successive filenames indicate the path, from volume 
directory to the file, that ProDOS must follow to find that particular 
file. The maximum length for a pathname used in a command is 
64 characters, including slashes. 


Examples: 


/EMPLOYEES/MARKETING/DIVISION. 1 — 
/SPORTS/FOOTBALL/THE.49ERS/QUARTERBACKS/MONTANA 
/BIGDISK/RECORDS/MAY/JELLY. BEANS 


Ars command that requires you to name a file will accept a 

patnname or a partial pathname. A partial pathname is a portion 

of a pathname that doesn't begin with a slash. The maximum x 
length of a partial pathname is 64 characters, including slashes. 


These partial pathnames are all derived from the sample x 
pathnames above: 


MARKETING/DIVISION. 1 5 
DIVISION. 1 
THE. 49ERS/QUARTERBACKS/MONTANA 


When you use a partial pathname, ProDOS does one of two things. 

it usually adds the prefix, a pathname that indicates a directory, to 

the front of the partial pathname to form a complete pathname. = 
But if the prefix is empty, or if you use either the siot option or the 

drive option (described in the section “Syntax’’) in the command, 

the name of the volume specified by the slot and drive options is ~ 
used instead of the prefix. 
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Create a new directory. 


Create a binary file in volume 


directory, $6, ۰ 


ہا مم رو بر .سے ل سد رجہ 
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This command normally sets the value of the prefix, but if no 
options are used, the value of the prefix is displayed. If the 
command is used without options in a program, the next INPUT 
statement reads the value of the prefix. H a slash is used in place 
of pn, the prefix is set to empty; the volume specified by the 
default stot and drive is then used as prefix. Otherwise the 
standard rules for pn and the slot and drive options hold. The 
maximum length for the prefix is 64 characters, including slashes. 


Possible Errors: 


EKHHGE ERROR Hil DEVICE COHHECTEU 
PATH HOT ۴(۵ lei ERROR 

IHVURHLID GFTIUR FILE TYPE MISMATCH 
SYHTRX ERROR 





CREATE pn [,Ttype] L, Ss] LDzt] 


Use the CREATE command in either immediate or deferred mode. 


Examples: 
CREATE .FHAOHE-HEHDIR TOIR 
CREATE FOTO ,D2,,2& TEIH 


Creates a file of the indicated type and name. Tabie A-2 shows the 
different file types. This command is primarily used for directory 
files. You must create a directory before saving a file in it. 


Possible Errors: 


RANGE ERROR Ha D 
WEITE PROTECTED PATH 
1.0 ERROR n 
IHVRLID OPTION 5 
DIRECTORY FULL 0 
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Summary of the Options 


& 


pn 


,D# 


Decimal or Hexadecimal Integer. ۶ can be replaced by a 
decimal integer, or it can be replaced by a hexadecimal 
number by preceding the hexadecimal digits with a 
dollar sign. The permitted values of # depend on the 
option. 


Pathname or Partial Pathname. See the section 
"Pathnames." 


Slot Number. ٭‎ specifies an Apple ۱۱ slot that contains a 
disk - ^ntroller card. # initially defaults to the slot from 
whi °*roDOS was started up. It subsequently defaults 
tot. ast value specified for this parameter. + must be 
in the range 1 through 7. 


If + refers to a siot which does not contain a disk 


controller card, you will get the Hii GE’ Tor 
CONHELCTED error message. 


Drive Number (either 1 or 2). # initially defaults to one. 
it subsequently defaults to the latest value specified for 
this parameter. 


If , S4 is used without this option, ,D# defaults to one. 


۱] # refers to a drive that doesn't exist on the controller 


سپ . 
1 


TEL! error. 


COHHNHEC 
Number of Fields. Used with sequential and random- 
access text files. = specifies a field whose position in 
the file is + fields ahead of the current file position. 

# defaults to 0, which does not change the file position. 
Note: EXEC always sets the pointer to the start of the 
named file, so + is always relative to 0 when used with 
EXEC. Although + has a maximum value of 65535, if 

# specifies a position past the end of the record or the 
end of the file, the position pointer stops at the end of 
the record or file, and the CLT LF OATS error message 
is returned. 


For DOS compatibility, both the options ,F and + 
indicate a number of fields when used with the EXEC or 
POSITION commands. 
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LOCK pn LSZ]LD£] 


Use the LOCK command in either immediate or deferred mode. 
Example: 


Lack «GATES-PEARLY 


This command protects the file indicated by pn, Sz, and D# from 
being accidentally deleted, renamed, or changed. A locked file is 
indicated in the catalog by an asterisk (*). 


Ro با‎ 


Possible Errors: 


EHHGE ERROR HG DEVICE CONNECTED 
WRITE FROTECTEG FATH HOT FOUND 

ERROR THVALIO OFT DOH‏ 0ہ] 
SYHTAS ERROR‏ 
سل 


UNLOCK pn LS#I LDF] 


Use the UNLOCK command in either immediate or deferred mode. 


Example: 


UNLOCK RECIPES, 5 
i 


if the file indicated by pn, Sz, and D& is locked, you must unlock it 
before you can alter, rename, or remove it. 


Possible Errors: 


EHMGE ERROR Hil DENICE COUHHECTELU 
WRITE PROTECTED PATH HOT FOUN 

1 لا‎ م٣۳‎ 1:۸8۲ 10 OFT 0! 
SMTA ERROR 


Filing Commands 
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Table A-2. The File Type Abbreviations 





snum 


Abbreviation 


DIR 
TXT 
BAS 
VAR 
BIN 
REL 


* $Fe- 


SYS 
SYS 





At Line Number. # indicates the number of the first 
program line to be executed by the RUN or CHAIN 
command. The default is the first line in the program. If 
there is no tine with the number +, an error is returned. 


Slot Number. snum is used with the IN# and PRE 
commands. ۱۲ can have any value from O through 7. 
snum is the slot number of the device with which 
subsequent data (either input or output) is to be 
transferred. An snum of 0 specifies the Apple 5 
normai routines for ۰ 


File Type. type is a three-letter abbreviation that 
indicates the type of file specified by the command. The 
possible values for type are given in Table A-2. 


E مس‎ E E e m 


Directory 


Text 


Applesoft Program 
Applesoft Variables 


Binary 


Relocatable Code 


File Type 


User Defined 
ProDOS System File 
ProDOS System Program 


* + is an integer from 1 to 8. 


س س 


As an example, the ProDOS command that has the syntax 


READ pn [,R#] (,F 4] [,B] 


can be interpreted as 


EEn بل‎ VAS 


by the following process. The command word READ is in 
uppercase, and must be typed exactly as shown. The symbol for 
the pathname pn is in lowercase; it is replaced by the pathname 
SBIGÜISE;MEHGZ.The option .R# becomes , E 38 indicating 
that data is to be read from record number 100 of the random- 


access text file 21 Î SF 
The option ,F# is replaced by . F 


ToT‏ سا 


ہے 


Ve MEMES, which must already be open. 
= indicating that the first two 


fields in record 100 are to be read and discarded before any data 
is taken from the record. The ,8 option is not used. 
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Bring BASIC program in file 
DOW.JONES in prefix directory into 
memory. 


m tomm oe ee ee س چچ س سس سی‎ 


The RUN command, without any parameters, causes the BASIC 
program currently in memory to be run. 


Possible Errors: 


RAHGE ERROR HO DEVICE CONNECTED 
FATH HOT FÜOUHU Il ERROR 

HVALIO GPTIUH FILE ee MISMATCH 
PROGRAM TOO LARGE SYHTRE ERROR 





HHOUOEF'ü STATEMENT ERROR 
LOAD pn S24] L,Dz] 


Use the LOAD command in either immediate or deferred mode. 


Example: 
LOA COW, JONES 


This command tells ProDOS to search for the Applesoft program 
file (type BAS) with the name indicated by pn, Sz, and Dt. If there 
is such a file, its program is loaded into the Apple Il's memory. The 
program can then be changed, listed, run, or saved. LOAD closes 
any open files (except EXEC files), and erases any BASIC program 
in memory before placing the new program in the Apple 5 
memory. 


The instruction LOAD, without any parameters, attempts to load a 
program from cassette tape. 


Possible Errors: 


ERHGE ERROR 
FETH HOT FRU 
IHMVALIO OFTIOH 


PROGRAM TOO LARGE 





LL‏ ہس 


BASIC Program Commands 





eo mamas prar o etna‏ عي ل به yr‏ سويب شور سور aea 7o mace CI C‏ سد سر جا ا 
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کر وش ."ات 





Set prefix to /PROFILE/WORKFILES/. 


Set prefix to name of volume in siot ۰ 
drive 1. 


Make prefix empty. 
Display the prefix. 


For each file in the directory these commands display from left to 
right on the screen 


e an asterisk if the file is locked (see the LOCK command) 


€ the file's name 
€ a three-letter abbreviation of the file’s type (see Table A-2) 
e the number of 512-byte blocks that the file occupies 


e the date the file was last modified (Mo/Da/Yr Hr:Mn:Sc) (only 
Mo/Da/Yr is displayed by CAT) 


e the date the file was created (Mo/Da/Yr Hr:Mn:Sc) 


e the /ogical end of file [see section "ENDFILE (Maximum File 
Sizes)" in Chapter 3 and section ''The End of File" in Chapter 7] 


e the file's load address (in hexadecimal) if it is a binary file, or its 
record length (in decimal) if it is a random-access text file. 


When you catalog a volume directory, the number of free blocks, 
used biocks, and total available blocks on that volume are 
displayed. 


Possible Errors: 


RRHHGE ERROR ذالم‎ DEVICE COHMECTED 
PATH HOT FOUND 1 لا‎ ERROR 1 
THMALIC OFT 1 HO BUFFERS AVATLABLE 
FILE TYPE MISMATCH ZYHTRX ERROR 

FILE ۱۲ 


—B— ي ٽن ٽڪ‎ Á———————m— 


PREFIX [pn] LS#]LD#] 


Use the PREFIX command in either immediate or deferred mode. 


Examples: 

PEEFIX :;FEOGFILE-;AHOEKFILEZ. 
PEEFIX OL 26 

FREFIX 

PREF I 
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5 Used from within a BASIC program, it loads and runs the BASIC 
program specified by pn, S#, and D#, leaving the names and 
values of all the current variables in memory. This means that a 
program can operate on the results of the previous program, and it 
can leave data for any subsequently chained program. 


If the @# option is used, execution of the indicated file begins at 
the specified line; if that line does not exist, the next highest line is 
run. 


Possible Errors: 


RANGE ERROR HO DEVICE COHHECTED 
FATH HOT ٤۵ Il ERROR 

OPTION FILE TYFE MISMATCH‏ 5ئ۲۸ 
PROGRAM TOO LARGE SYHTAS ERROR:‏ 


BASIC Error: 


۱۱۳۱2۶۶ ۲۵ STATEMENT ERROR: 


eel 


STORE pn [[S#]LD#] 
Use the STORE command in either immediate or deferred mode. 
Example: 

Store all BASIC variables. STORE -GAMES<BIHGO, VARS 
This command packs ali the currently defined BASIC variables, 
and writes them to the file (type VAR) indicated by pn, S£, and D#. 
These variables may be returned to memory using the RESTORE 
command. 
Before storing Applesoft variables, ProDOS compacts the 


Applesoft string space. This may resuit in a delay of two to four 
seconds before the disk is actually accessed. 


Possible Errors: 


FANGE ERROR HO DEVICE COHHECTED 
WRITE PROTECTED PATH HiT ۴ا٢‎ 

I-Q ERROR DISK FULL 

FILE LOCKED IHVRLID OPTIOW 

FILE TYPE MISMATZH ZYHTAS ERROR 


DIRECTORY FULL 


Programming Commands 
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حم ست مف میم لو ويف ia P‏ لمهم 


Delete EXPLETIVE file. 





RENAME pn1,pn2 [SE] 504%] 


Use the RENAME command in either immediate or deferred mode. 


Example: 
RKEHRME SEPERATE, SEPARATE, 34, DI 


Changes the name of the file indicated by pn1, S#, and D# to the 
name indicated by pn2, S#, and D#. This command cannot move 
a file from one directory to another; it can only change the name of 
a file within its directory. You cannot rename a file that is locked. 


Possibie Errors: 





BAHGE ۳ Hl DEVICE CONNECTED 
WRITE PROTECTED PATH NOT FOUND 

Teal ERROR FILE LOCKED 

THVALIC ZPTIOH SYHTRS ERREUR 
LUPLICHTE FILENAME FILE Busty 
DELETE pn [S4] LD#] 


Use the DELETE command in either immediate or deferred mode. 
Example: 


؟١‎ P سا‎ ۳ no 1 
DELETE ESPLETIVE 


۳1 


Removes the file indicated by pn, S#, and D# from its directory. 
The file must not be open or locked. if the file is a directory file, it 
must be empty. You cannot delete a volume directory. 


If a program tries to delete a nonexistent file, ProDOS returns the 
FATH HOT FüLlHD error message. To prevent this, open the file 
(which creates it if it doesn't yet exist), close it, then delete it. 


Possible Errors: 


RAHIGE ERROR HO DEVICE CONHECTED 
WRITE PROTECTED FATH HOT ۱۱۵ 

I. ERROR FILE LOCKED 

HVRLID OPTIC S'HTAM ERROR 

FILE ۷ 
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See the description of PRz in 
Chapters 5 and 9 for more details; also 
see the Apple I! Reference Manual. 


Get input from slot 2. 
Get input using routine at $300. 


See the description of INz in 
Chapters 5 and 9 for more details; also 
see the Apple if Reference Manual. 


vH ARMIS eee RO np cn سے‎ m ee e ans M c Iam o0 سرع‎ 


Once the address of the output routine is changed, ProDOS 
performs a jump to this new address. The first portion of the code 
at that address normaily performs initialization (such as starting 
up the disk in that siot). The code then resets the output routine 
address to indicate the true address of its output routine. 


If both snum and Az are used, the specified address is assigned 
as the output address for that siot. It does not redirect output: a 
subsequent PR# snum must be used for this purpose. 


Possible Errors: 


IE HO DEVICE COHHECTELD 
TIOHW ZYHTRS ERROR 


IN# snum! Ax 


Use the IN# command in either immediate or deferred mode. 


Examples: 


This command tells the Apple ۱۱ to take its input from a siot or from 
an address in memory. It operates by changing the address of the 
current input routine (stored in memory locations $38 and $39). All 
subsequent non-file input is taken, a character at a time, by the 
routine at the specified address. !f snum (a slot number) is used, 
the address of the current input routine is set to indicate the first 
byte of ROM on the card in that slot (SCsnum00). tf A# is used, the 
address is changed to #, and the byte at this address must be a 
6502 CLD (clear decimal) instruction. 


Once the address of the input routine is changed, 5 
performs a jump to this new address. The first portion of the code 
at that address normally performs initialization (such as starting 
up the disk in that slot). The code then resets the input routine 
address to indicate the true address of its input routine. 


Possible Errors: 


سر رس اج رح اس رہہ 


FARANDE ERROR Ho DEVICE COHHECTED 
THVALION OFTIZH SVHTAS ERROR 


Programming Commands 
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Run program in file /ANY/PROGRAM, 
regardless of program type. 


Load BASIC program from file AMOK in 


prefix directory and run it. 


Load BASIC program from file 
TWO.IN.ONE in prefix directory, and 
run it starting at line 1000. 





BASIC Program Commands 


This section contains a brief description of the BASIC program 
commands. 


- (DASH) pn L Sz] LDF] 


Use the DASH command in either immediate or deferred mode. 


Example: 


This command, called the DASH command, can be used in place 
of RUN, BRUN, and EXEC; it is the only command that runs a 
system program. Thus, it can be used to run programs of types 
BAS, BIN, TXT, and SYS (XXX.SYSTEM files). Note that everything 








currently in memory is lost when a system program is invoked. 
(See the RUN, BRUN, and EXEC commands for more details.) 


Possible Errors: 





PROGRAM TOO LARGE FANGE ERMI 

HO DEVICE COHHECTEL PATH HINT ازع‎ 

le ERROR 18118 OPTIUM 

NHO BUFFERS AWATLAELE FILE TYRE MISMATCH 
SYHTAS ERROR PILEcS? STILL نا‎ 
RUN pn L@FILSFILDFI 

Use the RUN command in either immediate or deferred mode. 
Examples: 

RUH AoE 


RM Teli, ۰ 


ONE, 8 


Loads the Applesoft program in the file indicated by pn, 52 
and D# (see the discussion of LOAD, below), and then runs it. 


If @# is used, then the program starts running at the specified line; 


if that line is not found, the next highest line is run. Without @+, 
execution starts at the program's first line. 
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Tp 


-m p‏ ہم 


Close all open files. 
Close /P/NOSE. 


The eftect of CLOSE on an EXEC file: 


see the section "The EXEC Command." 


For comparison, see the FLUSH 
command. 


ttm T A ml ge Ion m MM | e cA 00 سے‎ 
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ee eee ee‏ سیت ا سے 


Up to eight files can be open at a time. The commands OPEN, CAT, 
CATALOG, and EXEC—and - (DASH) when you use it to execute 
(EXEC commana) a file—all open a file. Only OPEN leaves the file 
open. 


The memory buffer for an open file is 1024 bytes long. If there is 
not enough free memory for a file's buffer to be allocated, the file 
cannot be opened. 





Warning 
A program must close all the files it opens. If it doesn't, data written to the 
file may be lost. 





Possible Errors: 





FAME ERROR HO DEVICE CAHHECTEL 
WRITE PROTECTED PATH HOT FOUND 

Taf ERROR DISK FULL 

18:۱۷0] OP ۲ Ho BUFFERS RURILRHELE 
FILE TY FE MISMATCH HoT DIEECT ۵ 
ZVHTAS ERROR DIRECTORY FULL 
CLOSE [pn] 

Use the CLOSE command in either immediate or deferred mode. 
Examples: 

CLOSE 


CLOSE «PeHOse 
The CLOSE command without options closes all open files (with 
the exception of EXEC files: see EXEC). If pn is used, only the 
specified file is closed. When a file is closed, any characters in the 
output part of the file buffer are written to that file, and its file 
buffer memory is released for other uses. 





Warning 
A program must close all files it opens. Failure to close an open file can 
resuit in loss of data. !f a program terminates because of an error, 


because a (CONTROL)-(C )was pressed, or tor any other reason, enter the 
CLOSE command from the keyboard before you do anything else. 





Possible Errors: 


li ERROR THMALIO OFT TH 


SSHTAS ERROR 


۱۱۱ ۲-۸ 


Text File Commands 
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v‏ موچ 


-ane ee 
۰ 


= e بو لوت‎ Ff a ہے‎ 


چ به ید و ہہ 


a ے ہہ‎ ov 9 


= اس‎ pw نات‎ i را ب‎ Áo 





Save current BASIC program in file 
BABY.SEALS. 


تج سس م 











SAVE pn [SE] LDF] 


Use the SAVE command in either immediate or deferred mode. 


Example: 
SAME EREY, SEARLS 


If the indicated file does not exist, a file with the pathname 
indicated by pn, S, and D# is created, and the current Applesoft 
program is stored in that file. ۱۲ the file is locked, the F TLE 
LOCKED error is returned. 





Warning 

If a file with the indicated pathname already exists, its contents are 
replaced without warning by the current BASIC program. A/ways /ock ail 
valuable files. 





The instruction SAVE, without any parameters, attempts to save a 
program onto cassette tape. 


Possible Errors: 


ERHGE ERROR HO DEMITE COMHECTEL 
WRITE PROTECTED PATH HOT FOUMD 

I.i ERRUR 018 FULL 

FILE LOCKED LHWALIO OFT 1 
FILE TYPE MISMATCH SYHTAM ERREUR 
DIRECTORY FULL 


Programming Commands 


This section provides a brief description of each of the BASIC 
programming commands. 





CHAIN pn Lez 1LSz]LDz] 


Use the CHAIN command in either immediate or deferrec 


Exampie: 


CHRIM -ERAMPLES@PRRET. THO 
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Prepare to write to end of file 
MORE.INFO, 


سے تھے سا | ہے re me‏ ات مھا کا ہے re er re ee me‏ اہ و سح Sp mae Rm mop ar ery‏ سا 


This command alters the current position, and prepares output to 
be sent to the indicated file. If Rz is used, the current file position 
is moved to the beginning of the specified record. If ۴۶ or B# is 
used, the current position is moved forward the specified number 
of fields and bytes. 


Once this command is given, all characters output by the program 
or by BASIC are placed in the specified file starting at the file's 
current position. The WRITE command is terminated by the next 
ProDOS command. 


Although you can open directory files (type CAT), and read from 
them, you cannot write to them. 


Possible Errors: 


ERHHCE EERIE WRITE PROTECTED 

Tet ERR DISK FULL 

FILE LOCKEL 180+610 DOFTIOH 
T سے ہر پچ‎ “mere ERED سس سے ہی سر ہے سا رح‎ 

HOT DBIREL 42 ZYHTHAS ۲۴۳۴٣۱۳ 

FILE HOT OFE} 


APPEND pn [, Ttype] LLZILS#I LDF] 


Use the APPEND command only in deferred mode. 
Example: 


Dor te 


This command opens the file specified by pn, Sz, and D#, moves 
the current position to the end of the file, and issues a WRITE to 
that file. If Lz is used (and is the same as the file's original record 
length), the current position is set to the beginning of the record 
immediately following the last record in the file. 


Once this command is given, all characters output by the program 
or by BASIC are placed in the specified file starting at the file's 
current position. The WRITE part of the APPEND command ís 
terminated by the next ProDOS command. 


ميب ب ب BM € a a‏ س 


Warning 
Be sure that your program closes al! appended files. Failure to do so may 


result in loss of data. 
سس‎ M... 1 5| "o ——————— — 


Text File Commands 
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Load BASIC variables. 


Send output to slot 1. 
Send output using routine at $300. 


Designate the ROM in slot 2 as the 
output routine for slot 1. Does not 
redirect output. 


. | 

ور 

af 
"—— 









RESTORE pn[,S2]L Dz] 


Use the RESTORE command in either immediate or deferred 
mode. 


Example: 


m, m T. =- por. Im 


This command clears the current BASIC variables from memory, 
unpacks the variables stored in the variable file (type VAR) 
indicated by pn, S&, and Dz, and puts the variables in the BASIC 
variable storage space in memory. 


Possible Errors: 





Tea "n 01 


E‏ د 


PRE snum|A#\snum ,A# 


Use the PRt command in either immediate or deferred mode. 


Exampies: 
FER i 

Sree BO 
۳851,82: کات‎ 





This command is used to send output to a slot; to send ouput to an 
address in memory; or to reassign the output address associated 
with a slot. it operates by changing the address of the current 
output routine (stored in memory locations $36 and $37). All 
subsequent non-file output is sent, a character at a time, by the 
routine at the specified address. If snum (a slot number) is used, 
the address of the current output routine is set to indicate the first 
byte of ROM on the card in that slot (S$Csnum00). If Az is used, the 
address is changed to +, and the byte at this address must be a 
6502 CLD (clear decimal) instruction. 
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Execute commands starting with the 
fourth field of the file PRIVILEGE. 


Other uses of EXEC are explained in 
Chapter 8. 


ہے nia‏ وس — 
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POSITION scans forward from the current position, character by 
character, until it encounters the #-th (RETURN)character following 
the current position. It then places the current position at the first 
byte following this (RErURN)character. If, in this search, it finds any 
byte in which no character has ever been stored (normally an end 
of record or end of file), the message EHD CF DATA is given. 


Possible Errors: 


FAME ERROR END OF ۳۵۷ 
1i ERROR THVALIO OF TION 
HOT DIRECT [4 چپ‎ ERROR 
FILE HOT ٣ژ‎ 

The EXEC Command 


The format and a description of the EXEC command are given in 
the section below. 


pO 


EXEC pn تارج‎ LS#]LD#] 


Use the EXEC command in either immediate or deterred mode. 


Example: 


EXEC FREIVILEGE,FZ 

This command causes the Apple ۱۱ to take all (non-file) input from a 
sequential text file instead of from the keyboard. This allows you to 
use a text file containing BASIC or ProDOS commands, or input to 
a running program to control the operation of your Appie I. 


The file indicated by pn, Sz, and D# must be a sequential text file 
(hereafter referred to as an EXEC file). ProDOS opens the EXEC 
file, reads and discards the number of fields specified by F# - 

or R#, and then starts reading commands at that position. When 
the end of file is reached, the EXEC file is closed. 


There can only be one EXEC command in effect at a time. If the 
EXEC file contains an EXEC command, the original EXEC file is 
closed and the new EXEC file is opened and executed. The CLOSE 
command, when issued from within an EXEC file, does not cause 
the EXEC file to close. If an EXEC file contains a RUN command, 
EXEC waits until the program ends; then the next command in the 
EXEC file is executed. 


The EXEC Command 
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Warning 

if a program is running while an EXEC file is open, an INPUT statement in 
the program reads its input from the EXEC file. Worse yet, if that response 
is an immediate-execution ProDOS command, the command is executed 
before the program continues. 





By the Way: If you type (CONTROL)-(C to stop an Applesoft program 
that is running while an EXEC file is still open, the remaining 


commands in the EXEC file are usually not executed. 


For compatibility with DOS 3.3, the F and R# options are 
functionally equivalent. 


Possible Errors: 


FAHLE ERROR HO OEVICE CONNECTED 
FATH MOT POUND lw ERROR 

IHWALIO OFTIUZM HO EUFFERZ BWAITLABLE 
FILE TYPE MISMATCH ZYHTRX ERRÜDE 

Binary Commands 


The binary commands are briefly described in the next sections. 5 





BRUN pn [7د4,]‎ LBF] [77ھ77۱,2.,]‎ ],3:77[ LDR] 


Use the BRUN command in either immediate or deferred mode. 
Example: 
BRUM SUPER, APJ 


The BRUN command loads the binary file (type BIN) indicated by 
pn, S#, and D# into the Apple Il's memory as specified by Az, BF, 
and L# or Ez. B# is the number of the first byte in the file to be 
loaded. AZ is the first memory address into which data is to be 
loaded; L# is the number of bytes to be loaded, and E# is the last 
memory address into which data is to be loaded (either جا‎ or Ez 
should be used, not both). If A4 is omitted, the file is loaded 
starting at the address from which it was saved. Once loaded, the 
file (which must be a machine-language program) is started by a 
machine-language jump (JMP) to address Az. 
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BASIC and ProDOS continue functioning if the machine-language 
program ends with a 6502 RTS instruction. 


Possible Errors: 


RANGE ERROR HO DEVICE COMHECTEL 
FATH HOT FüOUHLD 10 ERROR 
10+8610 ۱۱۴ ۲ ۷ FILE TYPE MISMATCH 


SYHTAA ERROR 


BSAVE مم‎ ,Az ,L#\,E# [BE] Ttypel, Sg] LDF] 


Use the BSAVE command in either immediate or deferred mode. 


Examples: 
BSAWE PICTURE. nHiez24, ا‎ 
ESAE FICT IRE. 00ات۳۹۴4‎ E£SFFF 


The BSAVE command stores the contents of a segment of the 
Apple ۱۱۹ memory into a file with the name indicated by pn, Sz, 
and D+, and the type indicated by Ttype. The default file type is 
binary (BIN). If the file does not yet exist, it is created. The segment 
is specified by the starting address A#, and either the number of 
bytes to be stored L# or the end address Es. Bz specifies the 
starting file position. 


The examples shown above both store a high-resolution picture 
from the second high-resolution picture area of memory. They 
have the same effect, but the second example uses hexadecimal 
notation and the E# option instead of the L# option. 


Possible Errors: 


RAHGE ERRUR Ho DEVICE CONNECTED 
PATH HOT ۷۵ WEITE PROTECTED 

Tei) ERROR DISK FULL 

FILE LOCKED INVALID ٣ 

FILE TYPE MISHMHTGh BYHTRHE ۴ 


DIRECTORY FULL 
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See the sections ‘High-Resolution 
Graphics With ProDOS" and "Installing 
Machine-Language Routines" in 
Chapter 9 for some important 
restrictions on memory usage. 
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BLOAD pn LAZ]LBzZ]LL £z |,EZ] را‎ Ttypel L, S2] ,Dz] 


Use the BLOAD commmand in either immediate or deferred 
mode. 


Examples: 
ELDAD PICTURE, S H2iss. تپ ےا‎ 
ELHA FICTURE, Boone, ASS, سا جام ع‎ 


The BLOAD command fills a segment of memory with data taken 
from the file with the name indicated by pn, S#, and D#, and with 
the type indicated by Ttype. The data is taken starting at file 
position B#, and is placed in memory starting at address A#. 

L# is the number of bytes transferred, and EZ is the end address; 
one or the other, but not both, can be used. If A# is omitted, the 
first byte is placed at the address from which the file was originally 
saved (using BSAVE). If L# and E# are omitted, the last byte 
transferred is the last byte in the file. 


For the examples, assume the file PICTURE has at least two high- 
resolution pictures in it, each 8192 bytes long. The first example 
shown above places the first 8192 bytes of PICTURE into the first 
high-resolution picture area, which starts at memory location 8192 
(decimal). The second example moves the second picture, starting 
at byte position $2000 (8192) in the file, into the second high- 
resolution picture area, which starts at memory location $4000 
(16384), and ends at memory location SSFFF (24575). 


Possibile Errors: 


EERIE ERROR HO DEVICE COHHECTEL 
FATH HOT تالا‎ Tell ERROR 

THVALIO GFTIGH FILE TYFE MISMATCH 
PROGRAM TOO LARGE ZTHTRER ERROR 
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The ProDOS Technical Reference 
Manual explains the many similarities 
between ProDOS and Appie tll SOS 
(Sophisticated Operating System). 
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DOS, ProDOS, and 
Applesoft 


About This Appendix E 


This appendix summarizes the differences between DOS and 
ProDOS. in so doing, it responds to three particular queries: 


e How dol tell what types of disks each of my programs can use? 


e How dol tell which files can be converted from DOS to ProDOS 
and which can be converted from ProDOS to DOS? 


e lalready know about DOS. What's so different about ProDOS? 


-my —M— € 0m 


The final part of this appendix lists the effects of ProDOS upon 
some of the Applesoft commands. , 


DOS Disks and ProDOS Disks 


The first question, “How do | tell what types of disks each of my 
programs can use?” is a good one. It is not the program, but the 
way the program is stored on a disk, that determines the types of 
disk drives the program can use. 


If a disk is formatted using the DOS command INIT, the programs 
on that disk use DOS, and DOS can use only Disk It Drives. 


If a disk is formatted using the ProDOS Filer, the programs on that 
disk use ProDOS, and ProDOS can use all disk drives made by 
Apple Computer, Inc. for the Apple Il. 


The question becomes: “How do | tell if a disk is DOS-formatted, 
ProDOS-formatted, or other?" 


DOS Disks and ProDOS Disks 


vc 2-0 05 1 "T‏ ےم ف ہیر Qoi et ——M—- — ^ en‏ سے سے aom a ey amroy y c o‏ را سے ہے 
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This problem only exists for Disk ۱۱ disks: a Disk ۱۱ disk could be 
formatted for ProDOS, DOS 3.3, DOS 3.2.1 (or an earlier version), 
Apple Il Pascal, or it could be unformatted. (If you have an 

Apple Ill, the disk could be SOS-formatted. In this case it is 
interchangeable with ProDOS disks.) 


e if it is a Disk II disk, and the name on the label begins with a 
slash, it is ProDOS-formatted. 


e |f itis a Disk Il disk, and the name on the label doesn't begin 
with a slash, follow the procedure given below. 


Run the ProDOS Filer and try the option LIST انالا"‎ 
DCIEECTOR'", If that works, it is a ProDOS-formatted disk. 
If it doesn't work, try using the DOS-ProDOS Conversion Program. 
Set the direction to DOS — ProDOS and then try to transfer files. If 
the program reads in a list of files, it is a DOS disk. If that doesn't 
work, the disk could be blank, copy-protected, or it could be an 


old version of DOS that used yet another method of storage. 


If you can't list or catalog the files, try starting up the disk. If it 
doesn't start up, the program was probably stored on the disk 

i using an old version of DOS. To use this disk, you need to use ine 
DOS 3.3 disk labeled BASICS (which you get when you buy DOS) 
and follow the instructions in The DOS Manual. ۱۱ the disk still 
doesn't start up, either the disk isn't formatted, or the information 
on the disk is damaged and is not readable. ١ 


If you aren't able to list a disk's files, but the disk starts up, the 
disk could be an Apple ۱۱ Pascal disk, some other language, or it 
couid be copy-protected. You probably have an instruction manual 
that teils about the filenames the program can use. If it mentions 
pathnames or prefixes, it is written using ProDOS; if it uses single 
filenames, it could be a DOS disk. 


By the Way: Once you determine a disk's type, label the disk with its 
type for future reference. Always use a soft-tipped pen when writing on 
a disk's label. 


LIL IIT LIES ETI) Converting Files 


Vm Mus شط‎ rama o بت‎ Ro Anima a ہے‎ ln te اط طس دہ‎ lt سف‎ Meine بک‎ 


ProDOS programs and data can use all types of disks made by 
Apple Computer, Inc. for Apple ۱۱ computers, whereas DOS 
programs can use only Disk Il disks. In addition, programs written 
using ProDOS read information from disks and write information 
to disks considerably faster than their DOS equivalents. 
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Table 8-1. File Conversion 
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Using the DOS-ProDOS Conversion Program, described in the 
ProDOS User's Manual, you can convert files from DOS format to 
ProDOS format, and back again. Tabie B-1 shows the 
correspondence between DOS and ProDOS files. 





Contents of File DOS Type ProDOS Type 
Text T = TXT 

Binary B — BIN 

Applesoft Program A ~ BAS 

Integer BASIC Program | ~ INT 
Relocatable Code File R مم‎ REL 

Other (ProDOS only) B — XXX 





When converted, text and binary files are immediately usable by 
programs of the other type. Applesoft files usually have to be 
modified before they can be used. The following sections explain 
the changes you must make when modifying a DOS program. 


The Differences Between DOS and ProDOS 


There are three main areas of difference between DOS and 
ProDOS. First, ProDOS is an entirely different program from DOS: 
it uses different code and different parts of the Appie Il's memory. 
Any DOS program that makes use of specific locations or routines 
in DOS will not work if converted. Likewise, programs that place 
assembly-language routines in memory may have to be changed 
so they don't overwrite parts of memory used by ProDOS. Details 
on the parts of memory used by ProDOS, and on the use of all the 
ProDOS routines, are given in the ProDOS Technical Reference 
Manual. 


The second major difference is the conflicting filename 
conventions and file organizations used by DOS and ProDOS. It is 
likely that you will have to modify both when converting a program. 
In addition, ProDOS does not support volume numbers. If your: 
program uses them, you will have to modify it to use volume names 
instead. 


The third difference is the command structure. Six DOS 
commands no longer exist, fourteen DOS commands have been 
improved, and eight ProDOS commands are new. Of these 
changes, only the commands that have been eliminated will affect 
the programs that you are converting. 


The Differences Between DOS and ProDOS 
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The PREFIX command is explained in 
Chapter 3. 


^ 








File Organization and Names 


This section assumes that you are familiar with the organization 
and names of ProDOS files. If you are not, read Chapter 2 of this 
manual. 


If a program refers to other files — for example, if it creates and 
uses a random-access text fiie, or if it chains to another program 
— then it is likely that you will need to change the way that the 
program names these files. 


First, the filenames in a converted program must all be changed to 
ProDOS filenames: they can be no more than 15 characters long, 
consist only of letters, digits, and periods, and must begin with a 

letter. 


Second, when the prefix is empty, ProDOS and DOS can use 
filenames in exactly the same way: each file has a filename, and the 
disk containing that file can be specified using the slot and drive 
options. Thus, if a converted program uses ProDOS filenames, it 
can work without further modification to the filenames, but only if 
the prefix is empty. The prefix is empty immediately after you start 
up ProDOS, and it also is empty after you use the command 
FREFIE 

However, it is preferable not to write or use programs that use files 
in this manner. Such programs place all files into a disk's volume 
directory. Because a disk's volume directory can hold no more 
than 51 files, it soon fills up if programs don't use directories of 
their own. You should revise each program so that it, and ail its 
files, are stored in a separate directory. 


DOS lets you assign a volume number to a disk when you initialize 
it. ProDOS does not support volume numbers. To modify a 
program that uses volume numbers, identify each disk by its 
volume name, not number. 
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DOS Commands That Went Away 
Six DOS commands are not supported by ProDOS. They are 





FP INIT MON 
INT MAXFILES NOMON 
FP and INT 


Because ProDOS supports only Applesoft BASIC, it has no need 
for commands that switch from one version of BASIC to another. If 
3 you use these commands, you get a 27۶۴۲۳۰ ERROR. 


3 وا سپ چک د اود کو بیود 


INIT 


Because of the different types of disks that must be initialized, it 
would take up too much mernory space for ProDOS to have a built- 
in formatting command like INIT. Thus, INIT is replaced by a 
command in the ProDOS Filer. Because you can no longer format 
a disk from within a program, it is now essential that you always 
have an adequate supply of blank formatted disks. 


ee re ۰‏ یورم 


Using INIT you could assign any name to the greeting program ona 
disk; with ProDOS, a greeting program must be named STARTUP. 
However, ProDOS lets you use a BASIC, machine-language, or 
EXEC program as the STARTUP program; with DOS, only BASIC 
greetings were possible. 


If ProDOS encounters the INIT command ina program, it gives you 
a SYHTHE ERROR. ! 


MAXFILES 


With DOS, the maximum number of files that could be open at 
once was three by default; this could be raised as high as 16 by 
using the MAXFILES command. With ProDOS, any program can 
have up to eight files open simultaneously. A 1024-byte file buffer 
is allocated to each file (or 512 bytes to a directory file) when it is 


See the ProDOS Technical Reference opened. 
Manual for more details on open files. 


The MAXFILES command is not supported by ProDOS, but it will 
not cause an error. 


The maximum BASIC program size for a 64K Appie Il is 


$A000 - $400 * Maximum number of open files 
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هص و — ناجم وو 


Refer to the specific command 
summary in Appendix A for the new 
syntax. 





MON and NOMON 


With DOS, the commands MON and NOMON allowed you to 
display all disk commands, disk input, and disk output without 
printing them. These commands are not supported by ProDOS. 
MON has been completely removed. If your program uses MON, 
you will get a S'HTR ERROR. NOMON is ignored by ProDOS, 
but will not cause an error. 


pÓ——————MM E ا‎ — P CÓ! —— —  — a LG 


Improved DOS Commands 


Fourteen DOS commands received facelifts. All can be used in the 
same manner as with DOS, so you don't have to change them 
when converting a program, but each has added features. The 
following sections describe the new capabilities of these 
commands. 


The improved commands are 


APPEND BLOAD BRUN BSAVE 
CATALOG CHAIN CLOSE IN# 
PR# OPEN POSITION READ 
RUN WRITE 

APPEND 


The APPEND command has two new uses. You can now use it to 
append new data to any type of file. You can use it also to append 
data starting at the beginning of the record immediately following 
the last logical record in a random-access text file. 


BLOAD 


The BLOAD command has three enhancements. You can now use 
it to load the binary image of any type of file, not just binary files. 
With DOS you had to load an entire binary file into memory. With 
ProDOS you can load any portion of a file. In addition, you have 
the option of specifying the number of bytes to be transferred as a 
start address and an end address in memory, or as a start address 
and the number of bytes to be transferred. 


BRUN 


As with BLOAD, you can load any portion of a binary file into 
memory and run it. The number of bytes can be specified using a 
start and an end address, or as a start address and the number of 
bytes to be transferred. 
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BSAVE 


You can now transfer (using BSAVE) information stored in memory 
into any type of file. The number of bytes to be saved can be 
specified using a start address and an end address, or as a start 
address and the number of bytes to be transferred. 


CATALOG 


You can now abbreviate the CATALOG command as CAT. 
CATALOG shows you an 80-column display of file information, and 
CAT shows you a 40-column display of information. Both show you 
the contents of a single directory; thus you must specify the name 
of the directory whose contents interest you. If you omit a 
filename, you see the contents of the prefix directory. 


In addition, CATALOG now displays information about the file's 
logical end of file, the file's record length (random-access text 
files); the file's last load address (binary files); and the dates when 
the file was created and last modified. 


CHAIN 


The CHAIN command now works for Applesoft programs (with 
DOS it did not). In addition, one program can chain to any line of 
another program, not just to the beginning of a program as before. 


CLOSE 


Now you must close a file from within a program. Failure to do so 
can result in loss of data. 


INZ and PRZ 


You can now use these commands to designate machine-language 
routines stored in memory as the character input and output 
routines. You can also use them to set the address of 5 5 

۱/۵ routines. 


OPEN 


You can now use the OPEN command to open any type of file for 
access. File buffers are now allocated when the file is opened, 
instead of in response to the MAXFILES command, as with DOS. 
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Appendix A contains summaries of 
these commands. 
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POSITION 


The POSITION command now uses either the F# option or the 
8+ option to read and discard the specified number (+) of fields 
from a file. The F# option is consistent with the ProDOS definition 
of fields; the R# option is for DOS compatibility. 


The ProOOS versions of READ and WRITE allow you to specify the 
number of fieids and bytes to be read and discarded. Thus, the 
POSITION command is not required by ProDOS; it is retained for 
compatibility with DOS. 


READ 


With DOS, the READ command allowed you to use the B# option 
to position forward a number of bytes before performing a read. 
The ProDOS version of READ allows you to use the F# and 

B# options to position forward a number of fields and bytes. This 
makes the POSITION command unnecessary for READ (and also 
for WRITE). 


RUN 
The ProOOS version of the RUN command aliows you to specify 
the line number at which the program is to start running. 


WRITE 


The ProDOS version of the WRITE command allows you to use the 
F# and B# options to position forward a number of fields and 
bytes. 


س ا 


New ProDOS Commands 


In addition to the usual DOS commands, ProDOS supports eight 
new commands. They are 


CAT CREATE FLUSH PREFIX 
STORE RESTORE - (DASH) FRE 


The following sections give brief summaries of each of these new 
commands. 
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CAT 


CAT displays 40 columns of directory file information, while 
CATALOG displays 80 columns. Both commands display 
filenames, their types, lengths, and last modified dates. CATALOG 
additionally displays the date the file was created, each file's 
logical end of file, and additional storage information (record 
length for random-access text files, and last load address for 
binary files). 


CREATE 


The CREATE command aliows you to create a file of any type, but 
it is primarily used to create directory files. BASIC (type BAS), text 
(type TXT), and binary (type BIN) files are automatically created by 
the SAVE, OPEN, and BSAVE commands, respectively. Text files 
can also be created by the APPEND command. Variable files 
(type VAR) are created by the STORE command. 
sg M myemaygn RPI پور‎ GTI ios مسارم‎ VT FT mom ALC RA EE ہج یسور‎ 

“You do not have to specify the size ofa created file. Additional blocks 
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FLUSH 


The FLUSH command causes all data that may be temporarily 
stored in a file's buffer to be written to the file. Using the FLUSH 
command after every statement that prints data to a file ensures 
that no data will be lost if the program is accidentally stopped. It 
aiso slows down a program significantly. 


PREFIX 


The PREFIX command allows you to set the name of the directory 
that contains the files with which you are working. With the prefix 
set, all files you name are assumed to be in that directory. 


If the prefix is empty, files are assumed to be in the main directory 
of the disk in the last referenced slot and drive. In this case, 
ProDOS filenames work exactly like DOS filenames. 


STORE and RESTORE 


The STORE command places the names and values of all the 
variables currently defined by a BASIC program into a variable file 
(type VAR). The RESTORE command adds the contents of a 
variable file to the variables that are currently in memory. 
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FRE command: see the section 
"Changes to Appiesoft." 


دب 
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Using HIMEM to place machine- 
language routines safely in memory: 
see the ProDOS Technical Reference 
Manual. 


Refer to the section “High-Resolution 
Graphics With ProDOS"' in Chapter 9. 
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- (DASH) 


This command, consisting of a single character, is called the DASH 
command. It is a generic RUN command, allowing you to run a 

BASIC, binary, EXEC, or system program. It does not let you use 

any of the specific options afforded by the RUN, BRUN, or EXEC 7 
commands. 


FRE 


The FRE command lets you use the fast housekeeping routines 
that ProDOS has. 


Changes to Appiesoft 


In order to keep a congenial working relationship between 
ProDOS and Applesott, it is necessary for ProDOS to intercept 
and perform some of the commands usually performed by 
Applesoft. The following sections explain the new enhancements 
or restrictions upon these ten commands: 


HIMEM HGR HGR2 TEXT 
INPUT IN# PR# TRACE 
NOTRACE FRE 





HIMEM 


Each time a file is opened, ProDOS uses the HIMEM setting to 
determine where it should place the file's I/O buffer. Because 
ProDOS manages memory in 256-byte chunks, you must always 
make sure that HIMEM indicates a 256-byte ($100) boundary in 
memory. 





HGR, HGR2, and TEXT 


Because the Apple ۱۱5 two high-resolution pages take up a 
considerable portion of the Apple ۱۱5 memory, ProDOS normally 
uses them as Applesoft program memory. If, however, you use the 
HGR or HGR2 command (or both), the Applesoft program (if any) is 
cleared out of the corresponding graphics page. The graphics 
pages remain reserved for graphics until the TEXT command is 
issued. 
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INPUT 


The Applesoft INPUT command has been made more useful. This 
command always reads an entire line of text, from either the 
keyboard or a file. As before, multiple variables in an INPUT 
statement are assigned strings of characters that are separated by 
commas in the input string. When you use ProDOS, the last 
variable in the INPUT list is assigned all the remaining characters 
in the line, including commas and colons. This means that you can 
now use a single INPUT statement, such as 


18 IHPFUT meg 


to read in any arbitrary string of characters. 





IN# and PRZ 


If you use one of these commands from immediate mode, it is a 
ProDOS command. Likewise, if you use one from within a 
program, preceded by (CONTROL)-(D), it is also a ProDOS 
command. If you use INzt or PR# from within a program without a 
leading (CONTROL)-(D), it is an Applesoft command, and would 
cause ProDOS to become disconnected if it were executed. Thus, 
ProDOS intercepts these Applesoft commands and ignores them. 


If you find that a PR# or IN# command from within a program is not 
having the proper effect, you probably forgot the (CONTROL)-(D ). 





TRACE and NOTRACE 


These Applesoft commands did not work with DOS. They now 
have their normal effect, described in the App/esoft BASIC 
Programmer's Reference Manual, on ProDOS commands as well 
as Applesoft commands. 





FRE 


If you use the FRE command within a program preceded by a 
(CONTROL)-(D), it is a ProDOS command. It is an Applesoft 
command if you use it in a program without the leading 
(CONTROL)-(D). In this case, housekeeping takes place using the 
slow Applesoft routines. 
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214 
214 
215 
215 
217 
217 
218 
218 
218 
218 
219 


RANGE ERROR (Code 2) 

NO DEVICE CONNECTED (Code 3) 
WRITE PROTECTED (Code 4) 

END OF DATA (Code 5) 

PATH NOT FOUND (Code 6 or Code 7) 
1/0 ERROR (Code 8) 

DISK FULL (Code 9) 

FILE LOCKED (Code 10) 

INVALID OPTION (Code 11) 

NO BUFFERS AVAILABLE (Code 12) 
FILE TYPE MISMATCH (Code 13) 
PROGRAM TOO LARGE (Code 14) 
NOT DIRECT COMMAND (Code 15) 
SYNTAX ERROR (Code 16) 
DIRECTORY FULL (Code 17) 

FILE NOT OPEN (Code 18) 
DUPLICATE FILENAME (Code 19) 
FILE BUSY (Code 20) 

FILE(S) STILL OPEN (Code 21) 
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~ Table C-1. Error Message Formats 


Refer to Chapter 5 of this manua! and 
to the Applesoft BASIC Programmer's 
Reference Manual for more details 
about ONERR GOTO. 


Error Messages 


When ProDOS detects an error caused by one of its commands, it 
normally stops the program that is running and displays a 
message describing the error. These messages are in addition to 
the usual messages generated by Applesoft. The source of an 
error messages is indicated by the character that precedes the 
message. Table C-1 illustrates these characters. 





Applesoft Message ProDOS Message 
TEVYHTRR م۸۳۴‎ ZYHTA= ERROR 





if a ProDOS message occurs when you are using the Monitor, the 
system is reset to BASIC before the message is displayed. 


Handling Errors From Applesoft 


Using Applesott's ONERR GOTO command, you can write 
Applesoft error-handiing routines to correct ProDOS and 
Applesoft errors that would normally interrupt your program. 


When a ProDOS or Appiesoft error occurs following an ONERR 
GOTO command in an Applesoft program, a code number for the 
type of error is stored in decimal memory location 222. The 
statement 


sets the value of E to the code of the offending error. The number 
of the Applesoft program line being executed at the time of the 
error can be found in decimal locations 218 and 219. The 
statement 


L = PEEK ¢218) + PEEK (2190 $ 23e 


۲٢1 


sets the value of L to that line number. 
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Table C-2. ProDOS Error Codes 





The ProDOS error messages, their codes, and the most common 
cause for each are described in Table C-2. Table C-3 shows which 
error messages are caused by each of the ProDOS commands. 
The ProDOS error messages are discussed in greater detail later 
in this appendix. The Applesoft error codes and their 
corresponding messages are shown in Table C-4. 


Code 





Most Common Cause 


Command option too small or large. 
No device found in specified slot. 
Write-protect tab on disk. 

Read beyond end of file or record. 
No file with indicated pathname. 


` No file with indicated pathname. 


Door open, or disk not formatted. 
Too many files on a disk. 

Attempt to write to a locked file. 
Option inappropriate for command. 
Memory full, file can't be opened. 
Disk file wrong type for command. 
Appie ۱۱5 memory too small 
(CHAIN). 

Command must be in a program. 
Bad filename, option, or comma. 
Volume directory has 51 files. 
Attempt to access a closed file. 
RENAME, CREATE name already 
used. 

File already open. 

Last program didn't close fiie(s). 
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Table C-4. Applesoft Error Codes 


Refer to the Applesoft BASIC 
Programmer's Reference Manual for 
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Code Error Message or Description 


0 
16 
22 
42 
53 
69 
77 
90 

107 
120 
133 
163 
176 
191 
224 UHDEF'E I 
254 Bad response to an INPUT statement. 
255 (CONTROL)-(C) interrupt attempted. 
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Discussion of ProDOS Errors 


The following sections list the ProDOS errors, their probable 
causes, and possible cures. 





RANGE ERROR (Code 2) 


Occurs when the value of an ProDOS command option is too large 
or too small. Table A-1 shows the maximum and minimum values 
for each option. 


Note: The use of values outside the indicated ranges does not always 
cause the FAGE EEROR message. Any ProDOS command option 
that is less than 0 or greater than 65535 causes the 2 "iT à EERIE 
message, not the =HHISE ۰۴۴۱:۶ message. 





NO DEVICE CONNECTED (Code 3) 


Occurs when you specify a slot that doesn't contain a card; a slot 
that contains a card not connected to its device; or if there is no 
disk in the drive (some drives only). 
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If you get this error when using a device for the first time, go 
through the device's installation instructions again. If you have 
used the device before and you get this error: 


1. You might have specified the wrong siot; try the command 
again. 


2. Turn off you: Apple li, open it, and gently rock the device's card 
back and forth until it is firmly seated. Close the Apple Il, start 
up ProDOS, and try again. 


3. If the problem persists, consult your dealer. 


p————M———Á—— — anal 


WRITE PROTECTED (Code 4) 


Occurs when ProDOS attempts to store information on a disk, and 
the disk drive does not detect a write-enable notch or cutout on 
the disk's outer case. These are the most likely causes: 


e There is an adhesive label placed over the disk's write-enable 
notch to prevent the writing or deletion of information on the 
disk. Remove this label, and the disk is no ionger protected. 


e There is no write-enable notch on the disk. This is true of the 
original copy of the /EXAMPLES disk, for example. If you are 
sure you no longer need the original disk, you can cut a notch in 
the disk's case yourself. Use another disk's notch as a template. 


——— € —s——— ——— ——— —— — 


END OF DATA (Code 5) 


Occurs when you try to retrieve information from a portion of a 
text file where no information has ever been stored. Any byte 
beyond the last field in a sequential text file, or beyond the last 
field of any record of a random-access text file contains the 

value 0. Zero is the ASCII code for a null character, a nothing, any 
command that causes the retrieval of this character results in the 
EHO عت‎ CATA message. The message usually occurs after an 
INPUT or a GET command; it can arise in several different ways: 


€ Too many successive INPUTs or an INPUT with too many 
variables. Each INPUT statement causes at least one additional 
adjacent field to be read into the Apple Il. Each INPUT variable 
causes one additional adjacent element to be read into the 


Apple il. 


e Too many successive GETs. Each GET reads one additional 
adjacent byte or character into the Apple Il. 


Discussion of ProDOS Errors 





-æ لب ھو‎ p o 


کو اس mee‏ سا - 


ہہ سے رس و — سويب سوام ہے الات 


moo asc on zi a - c. 0‏ سيو -qme -oe ue ve‏ 
ام ڪا me‏ ہے ee‏ و ی ا س اہ ہے س مج 0 ہے 











e The Bs (Byte) option in a READ or POSITION command is too 
large. In sequential files, this option must not specify a byte 
beyond the last (RETURN)character in the file. in random-access 
files, the B# option must not specify a byte beyond the last 
character in the currently selected record. Remember, 
the first byte in a file or a record is byte Q. 


e The F# (Field) option in a READ or POSITION command is too 
large. in sequential files, this option must not specify a field 
beyond the last existing field in the file. In random-access files, 
POSITION's F# option must not specify a field beyond the last 
existing field in the currently selected record. 


READ and POSITION scan forward through the contents of the 
file, byte by byte, looking for the F#-th (RETURN)character. ۲ 
either encounters a 0 byte (the null character) before finding the 
required (RETURN)Character, the EHD CIF CATA message is given 
immediately: it is not necessary actually to INPUT or GET the 
nuil character. 


e The F4 (Field) option in an EXEC command is too large. This 
option can specify the first field beyond the last existing field in 
a file, but attempting to specify the second field beyond the 
file's end causes the EHC JF GATA message. Remember, 
RO specifies the first field in a file. 


e The Rz (Record) option in a READ command specified a 
random-access file record in which nothing is yet stored. Before 
you can READ from a particular record in a random-access file, 
you must first WRITE some information into that record. RO is 
the file's first record, and so on. 


ProDOS uses the OPEN command's ۴ا‎ option for calculating 
where the R#-th record begins, so the OPEN preceding READ 
must use the same L# option value as the OPEN that preceded 
WRITE for that file. If no L# option is specified, the Lz with which 
the file was originally opened is used. 
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PATH NOT FOUND (Code 6 or 7) 


Occurs when a ProDOS command specifies a valid pathname that 
does not indicate an existing file, or when it specifies an invalid 
pathname. 


This message may arise in various ways: 





e You accidentally misspelled an element of the pathname. 

e You used a partial pathname that doesn't apply to the current 
prefix. 

e You used a partial pathname, and the disk indicated by the 
prefix is no longer on line. 

e The specified file does not yet exist. 

1/0 ERROR (Code 8) 


Occurs after an unsuccessful attempt to store data or retrieve data 
(ProDOS tries 96 times, then gives up). This message can occur in 
the following ways: 


e 
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The selected or default drive's door is open. Close the door of 
the disk drive. 


There is no disk in the disk drive indicated by Sz and D#. Puta 
disk into the drive and close the drive door. 


The disk in the selected or default disk drive is not formatted. 
Use the ProDOS Filer to format the disk. 


The disk is incorrectly seated in the disk drive. Open the drive 
door, pull the disk out, put it back in, close the door, and try 
again. 


The ProDOS command's Dz (Drive) option specified a non- 
existent disk drive. The default drive is now the non-existent 
drive. Just specify the correct D option with the next ProDOS 
command to reset the defauit. 


The system is trying to access a 13-sector disk. Use the 
DOS 3.3 program MUFFIN to update your disk to 16 sectors. 


A ProDOS command's Sz (Slot) option specified a slot that 
does not contain a disk controller card, or the snum option of 
PR# or INF specified a slot that contains no card. 
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Refer to Appendix A to see what 
options go with which commands. 









The default value of S# now indicates a slot that doesn't exist. 
First, you must get a prompt back, then you must reset S#. To 
reset the siot correctly: 


1. Press (CONTROL)-(RESET). 
2. If you see a Monitor prompt (*), press (CONTROL)-(C (RETURN). 
3. Type CATALOG 2#, O#. This time use a valid slot number. 





DISK FULL (Code 9) 


Occurs when ProDOS attempts to store information on a disk and 
finds that no more storage space is available on that disk. The 
number of free blocks on a disk is indicated when you display the 
catalog of the disk's volume directory. If you receive the DIZE 
FULL message, rest assured that all files are closed, and 
that ProDOS saved for you ail it couid (leaving you with some 
portion of your file not on the disk). If you receive this message 
while saving a file called STUFF, the first thing you should do is 


DELETE STUFF 


and then save your program on another disk that has unused 
room. 


ma ———— P ————————stn—À—————e——— 


FILE LOCKED (Code 10) 


Occurs when you try to APPEND, BSAVE, DELETE, RENAME, 
SAVE, STORE, or WRITE a locked file. Check the CATALOG 
display: the names of locked files are preceded by an asterisk )*(. 
Files are locked to prevent their being accidentally overwritten. 
Use another disk or unlock the desired file. 





INVALID OPTION (Code 11) 


Occurs when you use an option that is either non-existent or that 
is inappropriate for the given command. 





NO BUFFERS AVAILABLE (Code 12) 


When a file is opened by the APPEND, CAT, CATALOG, EXEC, 
OPEN, or - (DASH) command, a 1K buffer in memory is assigned 
for the temporary storage of data and file information. There can 
be a maximum of eight files open at a time. This error can occur if 
one of these commands is used when eight files are already open, 
or if there is not enough free memory for a buffer to be assigned. 
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The CATALOG, EXEC, and - commands 21106216 buffers, use 
them, and then release them; the OPEN command creates a buffer 
that exists until it is released by a CLOSE command. Files are not 
automatically closed when a program comes to an end. 


If you get this error, you cannot use any of these commands until 
you close one of the open files. 


This error also occurs if you try to BLOAD a file into the portion of 
memory used by the system (above HIMEM or below LOMEM). 
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FILE TYPE MISMATCH (Code 13) 


Occurs when a ProDOS command expects to use one type of file, 
and the specified file is of another type. This message arises from 
several different incorrect combinations of ProDOS commands 
with existing file types. Here are the correct combinations: 





Command File Type 
CATALOG pn, PREFIX pn pn must be a directory file (DIR). 


LOAD pn, RUN pn, SAVE pn, pn must be an Applesoft program 


CHAIN pn file (BAS). 
RESTORE pn, STORE pn pn must be an Applesoft variable 
f : file (VAR). 


pn must be a text file (TXT). 


pn must be a text file (TXT) unless 
Ttype is used, then file type must 
match Ttype. 

pn must be a binary file (BIN). 


pn must be a binary file (BIN) 

unless Ttype is used, then file type 

must match Ttype. 

- pn pn must be type BAS, BIN, TXT, 
or SYS. 


ا س 


The file named STARTUP in the volume directory of a startup disk 
must be of type BAS, BIN, TXT. 


EXEC pn 
OPEN pn, APPEND pn 


BRUN pn 
BLOAD pn, BSAVE pn 
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PROGRAM TOO LARGE (Code 14) 


Occurs when a ProDOS command attempts to place a disk file into 
the Apple li's memory, and finds the available memory insufficient 
to contain the entire file. This error can be caused by the CHAIN, 
LOAD, RESTORE, RUN, or - commands. You (or a previous 
program) may have set HIMEM too low for the new program to fit. 


If you get this error, you can split the program into smaller portions 
and use the CHAIN command to transfer between one portion of 
the program and the other. 


Remember that a program requires an additional 1K of memory 
for each file that is simultaneously open. 
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NOT DIRECT COMMAND (Code 15) 


Occurs when you try to use one of the text file commands 
APPEND, OPEN, POSITION, READ, or WRITE from immediate- 
execution mode. These ProDOS commands can be used only from 
within PRINT statements in program lines. 


pa ———— —dÜ— 


SYNTAX ERROR (Code 16) 


Occurs when ProDOS encounters a syntax error in a ProDOS 
command. Check the manual or the help screens for the exact 
syntax required for the command in question. The problem may 
be a pathname with illegal characters in it, an incorrect option 
symbol, a missing option, or a missing or incorrect separator 
(usually a comma). This message also arises if an option value or 
command quantity is a negative number or is greater than 65535. 
If all ProDOS commands inexplicably cause the 2 HT Ox ERROR 
message, ProDOS is not started up or is "disconnected" from 
input and output. To restore, type CALL i882 from BASIC (from 
the Monitor, press (CONTROL)-(c)to enter BASIC, then type 

CALL 1882), If this doesn't work, start up the disk again. 





DIRECTORY FULL (Code 17) 


A ProDOS volume directory file can hold up to 51 files. If a BSAVE, 
CREATE, OPEN, SAVE, or STORE command indicates a file in a 
volume directory that already contains 51 files, you get this error. 
To correct the error, save the file into another directory or onto 
another disk, then use the Copy File utility to move some files from 
the volume directory into another directory. 
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FILE NOT OPEN (Code 18) 


Occurs when a command is issued that can only act upon an open 
file. This error can be caused by the POSITION, READ, and WRITE 
commands. You must open a file before using any of these 
commands. 





DUPLICATE FILENAME (Code 19) 


Occurs when you CREATE or RENAME a file using a pathname 
that already exists. 





FILE BUSY (Code 20) 


Occurs when you CAT, CATALOG, DELETE, or RENAME a file that 
is already open. You must close a file before using one of these 
commands on that file. 





FILE(S) STILL OPEN (Code 21) 


Occurs when program execution is interrupted while one or more 


files are still open (for example, by another error or (CONTROL)-(C)). 


You must close all open files before you issue another LOAD or 
RUN statement. 


Discussion of ProDOS Errors 


4 سے ہما pee‏ سی ne‏ - 


am ہہ‎ 


- ای — M‏ —— کے مام سے mæ‏ ود 


- tees 


ہے یی ہس سک رو پچ رنہ 








وید سس و € مد سوہ + 





یو ود ام سے ہے 


pon 


Extras 





225 About This Appendix 
225 Using the System Date and Time 


226 


Using TIME 


226 Reading From ProDOS Directories 
227 The Appiesoft Programmer's Assistant (APA) 


228 
229 
230 
230 
233 
233 
236 
236 
236 
237 
237 


238 


Starting APA 

Automatic Line Numbering 

Turning Off Automatic Line Numbering 
Renumbering a Program 

Putting a Program On Hold 

Merging Two Programs Into One 
Deleting Remarks From a Program 
Displaying Control Characters 
Suppressing Control Characters 
Calculating a Program's Length 
Producing a Cross-Reference Listing 
Converting Decima! to Hex and Hex to Decimal 
Clearing the APA Program From Memory 


Appendix D: Extras 


oco 


oM M mme EY Tm ہے ا‎ 


n‏ —— — ——— .نب 































رہ جا ae me‏ سر سرت ے ہے ee EE TE LETHON r IA‏ عن ند 


نا ہو ہل ld‏ تھ مس ات ae‏ ےی فا n A‏ 


= Oper etm tem رت ہر ہے‎ tm we on 






: 


ع سم > 


/ $ 


Extras 


About This Appendix 


This appendix describes the useful programs that are stored in the 
directory /EXAMPLES/EXTRAS. They perform the following 
functions: 


e TIME allows you to read and set the system date and time so 
that your files are marked with the proper date. 


e READ.DIRECTORY is an example of how to read from a 
directory file. 


Using the System Date and Time 


ProDOS has two memory locations that contain the current date 
and time. if you have a clock/calendar card, instructions for 
making it work with ProDOS are in the section “Using a 
Clock/Calendar Card" in Chapter 9. 


If you don't have a clock/calendar card, ProDOS takes whatever 
date and time are stored in the system date and time locations, 
and marks all created and modified files with that time. The 
program TIME is an Applesoft program that allows you to read and 
set the system date and time locations so that your files are 
marked with the current date and time. 
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Using TIME 

With the /EXAMPLES disk in any drive, type the command 

RUM ."ERERHMPLEZ.EXTEHZ.-TIME 

and the values of the date and time locations in memory are 
displayed. If there is no time currently set, the messages 3 
SHO DATE: and Hii TIME: are displayed. The program asks 
you if you want to update the system date and time. If you say yes, 
you must enter the date in the form 

[ID MM Y 

(where DD = 01 to 31, MMM = JAN to DEC, YY = 00 to 99) 

and the time in the form 

HH:MM ۷ 

(where HH = 01 to 12, MM = 00 to 59, AM = AM or PM) 


When entering days, hours, or minutes less than 10, you must type 
in the leading O. 


To set the time on a clock/calendar If you have a clock/calendar card, this program does not set the 
card, refer to the manual for the card. time on the card. 





Reading From ProDOS Directories 


Like ail other ProDOS files, directory files can be opened and read. 
When you read from a directory file, ProDOS automatically 
interprets the information in that file, and passes it to you in an 
understandable and familiar form—it gives you the same lines of 
text displayed by the CATALOG command. For example, to list the 
/EXAMPLES directory, you can use 


D$ is (CONTROL)-(O ). 2 :اع م0‎ E4. 
Open directory. 1 لا‎ PRINT Of: "CREM -EXAMELES, TOIR" 
Prepare to read لیات‎ PRIHT OF: ۳۳۴۳۵۲ FER PLES" 
directory name, 3B INFUT L1 ۳ ; FRIHT Lit 
title line, 4d — IHFUT Let: FRINT Let 
blank line, 38  IHFUT Lat: FRIHT LZE 
lines of directory, eM INPUT L4t: FREIHT یا‎ 
until a blank is read. re IF | 5ك‎ 2; "" THEH GOTO تا‎ 
Print block use and close directory. zB INPUT Lit; FEIHT Lat 
Ba FEIHT GE: use SESHMPLEZ" 
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The first line returned is the name of the directory being read. If it 
is a volume directory, it is preceded by a siash. The next line read 
is the title tine, shown below. The third line is always empty. 
Subsequent lines, until the next blank tine, are the files in the 
directory. The block count is the last line read. This program is 
stored in the file /EXAMPLES/EXTRAS/READ.DIRECTORY. 


If you want to do interesting things with the string you have just 
read (such as write a program that lets you look through a disk's 
directories), you need to know the exact format of the returned 
string. A sample line from a directory tooks like this 
لے‎ NAME TYPE BLOCKS MODIFIED TREATED ENDFILE SUBTYPE 
, FILE. NAME BAS i4 بالق‎ 4:32 25-800-82 1911. 2801 


نے تو ME‏ لے T‏ 9 ہی ہو 


The specific contents of each character of a line read from a 
directory are listed in Table D-1. 





Table D-1. Directory Line Composition ie يل لب اي‎ 
Column Use 
1 Locked or unlocked 
2-16 Fitename 
18-20 File type 
23-28 Blocks used by file 
31-39 Date file was last modified 
41-45 Time of last modification (24 hour clock) 
2 48-56 Date file was created 
58-62 Time file was created (24 hour clock) 
64-71 Logica! end of file 
73 Subtype identifier: A = load Address 
R = Record length 
75-79 Load address (hexadecimal) 
76-79 Record length (decimal) 
wT ose oT TTT The Applesoft Programmer's Assistant (APA) 


The Applesoft Programmer's Assistant is a binary program named 
APA. It is in the EXTRAS subdirectory on the ProDOS BASIC 
Programming Examples disk. 


APA can save a lot of time when you write or change Applesoft 
programs. The table below fists APA's functions and the 
commands you use to perform them. Each command is discussed 
on the pages that follow. 


The Appiesoft Programmer's Assistant (APA) 
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Function Command 


Automatic Line Numbering AUTO 
Turning Off Automatic Line Numbering MANUAL 
Renumbering a Program RENUMBER 
Putting a Program On Hold HOLD 
Merging Two Programs Into One MERGE 
Deleting Remarks From a Program COMPRESS 
Displaying Control Characters SHOW 
Suppressing Control Characters NOSHOW 
Calculating a Program's Length LENGTH 
Producing a Cross-Reference Listing XREF 
Converting Decimal to Hex and Hex to Decimal CONVERT 
Clearing the APA Program From Memory EXIT 





n ———— ——— ———nÍáMH—— Ru 


Starting APA 
Here is how to start up the APA program: 


1. Insert the ProDOS BASIC Programming Examples disk in 
drive 1, and close the drive door. 


2. If the computer's power is not yet on, turn it on and go to Step 3. 
OR ` 


If the computer's power is already on, press 


(&)(GONTROL)-(RESET). 


3. When the disk drive's light goes out and the ProDOS BASIC 
Programming Examples startup display appears, type 


~ER TEE! 


T 


«mmt 
Re 


and press (RETURN). 


The drive whirs for a moment, while ProDOS relocates, loads. and 
initializes APA. 


By the Way: APA is loaded just below HIMEM, and HIMEM is reset to 
just below APA. Although they are both in memory at the same time, 
APA and any Applesoft program you load are kept separate and can't 
interfere with each other. If your program is extremely large, you may 
need some of the memory taken up by the APA, but this wili rarely be a 
problem. 
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After APA is loaded, the APA startup display appears: 


IS TT ee POET 1 w Tampane i omaes pn amy pg, OP رسس وم‎ mpg gprs mt St 
a RPPLESDFT PROGRAMMER ' 8 ASSISTANT. l 

VERSION 1.2 aoe 

“COPYRIGHT APPLE COMPUTER, 1979-83 i 





Eu TI MA ۱۲ سج‎ EINT e ام‎ 





مو نیمز 0 ih‏ 


With the Applesoft 3 prompt on the screen, you can use any of 
APA's commands. APA's commands can be used only in 
immediate mode—they cannot be part of another program. 


———— —Á———UMiÓ— —— —S —— ————— ' ' ——— QA 
Automatic Line Numbering 


The AUTO command makes it easier and faster to enter programs. 
It lets you specity 


è what iine number to begin with 


e the increment between line numbers. 


17 To specify a starting line number of 100 and an increment of 10, 
type 


ع سا M‏ --—— 


ا 


The space after ۲۷۱۱۲۱ is optional. The AUTO 188, Ík 
starting line number ar.d increment 


must be numeric integers in the range 1 
trom 1 to 63999. ue 8 and press (RETURN). When you then press (SPACE), the line 
number 14& appears automatically. ۱ 


After you type the rest of the Applesoft program line and press 
and (SPACE), the next line number, i iH, appears. 


To specify a starting line number of 100, without specifying an 
increment, simply type 


AUTO 158 
and press (RETURN). The APA sets the increment to 10. 


If you wish to leave a line number unused, press and 
then without typing an Applesoft program line—the next 
line number appears, and no statement is entered under the 
previous one. 


If you want to use a line number that the AUTO function doesn't 
provide (for example, to use the line number 15 when the starting 
line number is 10 and the increment is 10), just type 1 instead of 


pressing (SPACE). 
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if you change your mind about a statement while you are typing it, 
press (CONTROL)-(X). When you then press (SPACE), the same 


number reappears without the statement. 


A line number appears only if you press after the ل‎ 
prompt, so you can type a run-time command any time you see the 
prompt, as long as you don't begin it with a space. This means you 
can RUN or LIST your program, or SAVE it and LOAD another, 
clear the screen with HOME, or see the CATalog— just as if APA 
weren't there. 





Warning 
It is possible to overwrite APA with run-time commands. When APA is 
loaded, don't run a program that changes HIMEM or the ۱/۵ hooks. And 


don't press (RESET). 








Turning Off Automatic Line Numbering 


To turn off automatic line numbering, type 
MHHUHL 


and press (RETURN). MANUAL is the default when you load APA. To 
get automatic line numbering, you must use the AUTO command. 





Renumbering a Program 


The RENUMBER command renumbers the lines in all or part of a 
program in memory. You specify the starting line number and 
increment. 


Even better, this command also changes line references in GOTO, 
GOSUB, and ONERR statements! So if the program runs correctly 
before renumbering, it runs correctly after renumbering— unless 
you change the order of the lines. RENUMBER does not, however, 
change line references in REM statements, so check these 
yourself. 


By the Way: If a RENUMBER command would cause interleaving of 
lines or duplication of tine numbers, APA does not execute it. This 
would happen if a range of lines were renumbered so that its new 
numbers overlapped the numbers of another range of tines. The 
resulting error message is INTERLER'VED JR DUPLICHTE LINE 
NUMBER. 


iow Be ا‎ ۰ tae m 
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Let's start with an example. First, type HE to clear memory (this 
won't affect the APA program). Then enter this simple program at 
the keyboard: 


1 
z 
4 
5 
È 


تی تی مت بی f‏ 2 


PRINT "S" 

PRIHT ۳ 
PRINT "HM" 
PRINT "P^ 
PRINT "L" 
PRINT "E" 


t‏ سارہ“ ہم we vec‏ ہے مه zoa n‏ س و و" ا 


SAVE the program by typing SAE SAMPLE and press (RETURN). 


To renumber your SAMPLE program, type 


REHNE: 


m, m, 
۳ 


i 


and press (RETUAN). Your whole program is renumbered, starting 
with line number 100 and incrementing by 10. Try LISTing it: 


BE نا ی سا ی خی کی‎ LC من ساب وش مر ا ی وت ره رن‎ PA 


188 


118 FRINT g^ l 


FRIHT "S" 


1 28 PRINT "M" Ce ات ا‎ 


138 PRIMI ود‎ ver 
[ 48 PRINT "L* ار‎ 
150 PRINT E 





Qo ور‎ EBAR N یں وتم ام‎ i ہو کک‎ MCS o Los ہہ‎ i Va 4 E M edi یا‎ D TT — 


If you don't want to start with line number 100 and increment 
by 10, type, say: 


E HH HEE i igd40 4 


This results in 


B. | 


1 
1 1 
1158 
1288 
1254 


PRINT ۳ 
PRINT ۳ 
PRINT "M" 
PRINT "P" 
PRINT "L" 
PRINT "E" : 
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Load the SAMPLE program you saved earlier. To renumber only 
part of this program, you can specify the first and last old line 
numbers to be changed. For example, if you type 


Emi ei سوہ رت رر‎ A L3 4 rà پت 4 عم‎ 
REHUMEER lH, iB, io, 48 


(where the starting line number is 100, the increment is 10, and the 
first and last oid line numbers are 30 and 40), the result is 


14 FRI HT "se 
28 PRIHT "H" 
59 PRINT "ا"‎ 
BG PRINT "E" 
1868 PRINT "M" 
110 PRINT "ع"‎ 


گے mter‏ ور شک ری toa‏ نمی با Melee aew‏ 


Only the lines previously numbered 30 and 40 have been 
renumbered. Notice that the lines are in a new sequence, in 
keeping with their new line numbers. You can use RENUMBER to 
move subroutines around in a program. 


You can specify the first one, the first two, the first three, or all four 
RENUMBER parameters. RENUMBER uses a default value for 
omitted parameters. The default values are: 


<starting line number> 100 


<increment> 10 
«first line 0 
<last line> 63999 


Thus, these two lines are equivalent: 


T a 


- ؛: 


HUME 


rri 
Iri 


E 
mua 


A 
im 


t 
i 


— 
ا 


سے سے بس 
AC‏ 


m 
zi 
۱ 5 7 


LI pret Es 


1 n 
rm 
a1 


The RENUMBER command does not let you give two lines the 
same number or interleave two sets of lines. Instead, you see the 
Ae ud im ine ds " 


message iHTERLERUED CR DUFLICRTE LIME HUMBER. For 
example, if you load SAMPLE and type 


E‏ = رہپ ینم 
pt‏ 4 فی vial‏ و is E‏ 


2 


HEME; 


i 1 
(1 


you see the error message: this command would not only put 


line 50 between lines 10 and 20, but it would also put lines 40 
and 60 on top of lines 10 and 20. 
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Putting a Program On Hold 


Use the HOLD command to shelter a program above HIMEM, 
where it can't be erased by the loading of another program. This 
lets you load a second program into memory, then use the MERGE 
command (described in the next section) to combine the two 
programs. 


With a program in memory, type 
HULO 


m, سے‎ 


and press (RETURN). You see the message ۴۲۱۵۳۱ OM HOLE. 





Merging Two Programs Into One 


After putting one program on hold, you can use the MERGE 
command to combine it with another. 


Let's work with the SAMPLE program you created earlier. First, 
load SAMPLE and list it on the screen: 


18 PRINT "S" 
وع‎ PRINT "Re. 
30 PRINT ۳49 ا ا‎ 

40 PRINT "P" 

58 PRINT ہم‎ 

۶8 PRINT "E" 


tis ^ ۰ 
جام‎ mah M Ee ae مر اع الات ا‎ TS بد‎ UR INS o v of Mee 


a n AIR‏ ° ہچ اھ nr enn DIVOM coercendi. coe‏ ے gE Ta Cmm‏ الما 


c‏ 3 سی 


Now delete lines 10, 30, and 50 by typing 
15 
38 


5 
and pressing after each line number. 


When you list the program, you have 


28 FRIHT "A" 
48 PRINT “F” 
ER PRINT "E" 


The Applesoft Programmer's Assistant (APA) 





—————r———-—-—-i1o- »‏ سا 


Ó‏ | 7 سے CD cá m‏ وہ تھے TR o enim‏ وب = ی ee e oaa msc‏ € ہے چپ cac‏ سج qd CR)‏ دو FM. REO‏ € ہے ہے 





pm" 


سا A——À‏ سر ————— 


لم at‏ مسب 


س --0———— 








Save this shorter program under the name APE. Now type 


Lil di 
uum ^ 


to put APE on ۰ 


Now reload SAMPLE, and delete lines 20, 40, and 60 from it. This 


lists as 


18 PRINT ۳ 
39 PRIHT "M" 
S8 PRINT "L" 


2 


Save this program under the name SML. Now type 


Dmm Fang 
MERCE 


and press (RETURN); then type 
Eur 


and press (RETURN). The result: 


ENE NE OE NR شی مس شی‎ 3 
۶8 PRIMI "Si ا‎ 
28 PRINT "Rh" S کرت‎ 
TE PRINT "Wesce 
44 PRINT ۲ ۰ 

Sü- PRINT "EY. 

Bü PRINT "ET: 





NA" 





اہ وکا نه مات مب شی اسر 2 .سد ہہ E uie‏ 1211111111 ”ساعد ad me‏ مح یگ 


Presto! The program you carved up so diligently is now whole 


again, and sorted by line number. 


if you had renumbered SML before merging, for example, by 


typing 


ES wort ipngiec Ci 45:3: 
٣۵11182 Late, 


so that SML looked like this 


188 PRINT "S" ےت‎ 
388 PRINT "M" 
388 PR INT "L^" 


Yea, سو‎ te نيك‎ o 7 -c 8 ای یکا و کو‎ eil ا ا عو يبا‎ ae 
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-~-e 


en. m: 


ENE am sco o WS sit NET IC are mee c RR IL. 


you would have gotten a different result. If you typed 


MERGE 


you'd get 

26 PRINT "A" 

PRINT "P"...‏ تاك 

64 PRINT "E" 

1886 PRINT "S" 

204 FRINT ٣ 

580 PRINT "L* ۱ 


The MERGE command, unlike the RENUMBER command, can 
create duplicate line numbers. For example, put APE on HOLD, 
then LOAD SML. Renumber it by typing 


pU‏ 4 وس ےھ مسا pet‏ سس سو 
Le‏ اتات REHLUMEER‏ 


and the listing is: 


TN smod. qeu]. ORR e RR EO HH ہے‎ D I MAD رر سس عي وہ ری ور‎ ro PIYER نت‎ yy A n 


£8 PRINT "Sho د۳‎ Co 7 
“AG PRINT COELO e e 


یں E‏ کات کت k Attn‏ لمت جع لسعاي unco C iota‏ م چ 
Both APE and SML now contain lines numbered 20 and 40. Now‏ 
type‏ 


MERI 


m 


and you see the message 


١ہم‎ MER دس‎ Munch n uem neq Lom Hee fo Ace HP. o mme arem art e C NE P Dn گی و‎ 
“DUPLICATE LINE NUMBER 
pu 
48 


CONTINUE? 

If you press to continue in spite of the duplicate line numbers, 
the line from the HOLD area has priority, and the other iine with the 
same number is deleted. The listing is then: 


PRINT "AS 
PRINT ٩ 
PRINT "P" 
PRINT "E" 


mna 
id لک کا‎ ١ 
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Controi characters are characters 


produced when you press [CONTROL 


together with some other key. 





if you try to use MERGE when there is no program on hold, you get 


the message Hii ASOLO rice. 


The MERGE command can perform wonders, and save you a lot of 
time. But it can also wreak havoc. Before typing the MERGE 
command, SAVE each of the programs to be merged. 





Deleting Remarks From a Program 


The COMPRESS command removes documentation remarks 
(program lines that begin with REM) from the program in memory. 
COMPRESS lets you maintain two versions of a program. The one 
that contains REM lines is easier to maintain, and the compressed 
version runs faster and uses less memory. 


To use this feature, load a documented program, then type 


oe ss‏ یا 


and press (RETURN). The program in memory is compressed, and 
you can then save it under a different name. A message tells you 
how many bytes are saved. If you later revise the program, change ` 
the documented version and make a new compressed version 
from it. 





Displaying Control Characters 


Use the SHOW command to make the control characters in your 
program visible. Type 


۳ 


and press (RETURN). If the program contains any control 
characters, they are displayed in inverse video when you LIST. 





Suppressing Control Characters 


After using SHOW to make control characters visible, use the 
NOSHOW command to make them invisible again. Type 


MOSHE 


and press (RETURN). Control characters are no longer displayed. 
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Calculating a Program's Length 


Use APA's LENGTH command to determine the length of the 
program in memory. Type 


LEHGTH 


and press (RETURN). The program's length in bytes is displayed, in 
both decimal and hexadecimal form. 


س 
Producing a Cross-Reference Listing‏ 


The XREF command produces an alphabetical cross-reference 
listing of the Applesoft program in memory. The listing shows each 
variable in the program, together with the numbers of all lines in 
which the variable appears. 


Load the program you wish to cross-reference; then type 

AREF 
and press (RETURN). After a pause that depends on the length of 
the program, the variables and their line numbers are listed on the 
screen. Note that all variable names are shortened to two 


characters (Applesoft distinguishes only the first two characters of 
a variable name). 


Five kinds of variables are identified by a suffix: 


f represents a string 

9 represents an array 

represents a string array‏ ے 

“a represents an integer variable 
^S represents an integer array 


You can interrupt the cross-reference listing by pressing 
(CONTROL)-(S). To resume an interrupted listing, press 
(coNTROL)-(S ) again. 
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Converting Decimal to Hex and Hex to Decimal 


Use the CONVERT command to convert decimal numbers to 
hexadecimal and hexadecimal! numbers to decimal. 


For example, to convert decimal 255 to hexadecimal, type 


and press (RETURN). The program immediately responds by 
displaying 


where حتت‎ is the hex equivalent of decimal 255. 

To convert hexadecimal 2B to decimal. type 

and press (RETURN). The program responds with 
4zosüdzE 


where 4 is the decimal equivalent of hex 2B. — 





Clearing the APA Program From Memory 


To untink APA commands and return to the system all the memory 
that was being used by APA, type 


T d 
EX iod 


i‏ عل 


and press (RETURN). Once you've used the EXIT command: typing 


any more APA commands results in a ' HTIASERRUR. 


To reload APA, type 


EUTEI rem نس‎ m] 


and press (RETURN). 


Appendix D: Extras 


So momar me eee e peor en 








Tomen mee e ec me pn - 








ae 














we —-‏ مہہ و 





.ہم مت سس تس ۱۳ 





| = 


"~ - ~ 





| 
| 


on 


we eee ای‎ 


- 


Cop. À— ہے‎ 


A 


ne «m 


m 











MÀ re — €‏ تل لہ — سے 
E —M— ———À‏ 
: — — ~ = - = —— 


: وت‎ A oral 
~ nnn Ha us em 
Dest 5 





om Ms 











«m cem‏ ست و 


M 


Doa TEA en nii, 
M, owe ملكت ا‎ ae یس‎ 2 
2 ala Ct d تس وت‎ CR کی ماق‎ b n, مق‎ Jd توت‎ 


t 


Glossary ۱ 


This glossary defines the terms used in this manual as they apply 
to ProDOS. Refer to other sources for more complete definitions. 


address A number that specifies a single byte of memory. 
Addresses can be given as decimal integers or as hexadecimal 
integers. A 64K system has addresses ranging from 0 to 65535 (in 
decimal) or from $0000 to SFFFF (in hexadecimai). 


APPEND Attach to the end of. The APPEND command is used to 
write new data to the end of an existing file. l 


ASCII An acronym for the American Standard Code for 
Information interchange. This code assigns a unique value from 

0 to 127 to each of 128 numbers, letters, special characters, and 
control characters. It is the code with which the Apple Il represents 
the characters entered at the keyboard. 


back up To make a spare copy of. It is a good habit to back up 
important files and disks frequently. 


binary Encoded using the base-two numbering system 
consisting of the two digits, O and 1. A single binary digit, a 0 or 
a 1, is called a bit. 


binary file A file whose data are to be interpreted in binary form. 
Machine-language programs and pictures are stored in binary 
files. In comparison, the data in a text file are interpreted as a set 
of characters. A ProDOS binary file is indicated in a catalog by the 
abbreviation BIN. 


BLOAD Binary load. The BLOAD command causes the binary 
form of a file to be placed in memory. if the file is not a binary file, 
its uninterpreted image is placed in memory. 


block 512 bytes of data. This is the unit of storage used by 
ProDOS. ProDOS regards the information stored on disk and in 
memory as collections of blocks. 


BLOCKS When you use the CAT or CATALOG command, the 
column on the screen labeled EL CC Ez lists the number of blocks 
of disk space occupied by each fiie in that directory. 
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BRUN Binary run. The BRUN command causes a binary program 
to be brought into memory and run. 


BSAVE Binary save. The BSAVE command causes the binary 
data in a portion of memory to be saved in a disk file. If the file is 
not a binary file, the data is not automatically encoded before 
being placed in that file. 


buffer A temporary storage area. ProDOS uses a file buffer as a 
temporary resting place for the characters being read from or 
written to the file. 


byte A unit of computer memory. A byte is eight bits (Binary 
digiTS) long, and is thus capable of expressing a range of numbers 
from 0 to 255 (2 to the 8th power is 256). Each character in the 
ASCII code is represented within a single byte. 


CAT or CATALOG These commands cause a list of the names 
and characteristics of all the files in a directory to be displayed. 
Both are identical. This display of information is often referred to 
as a catalog. CAT displays a 40-column list; CATALOG, 80. 


CHAIN The CHAIN command runs a BASIC program without first 
erasing the variables currently in memory. 


CHR$ This Applesoft function, when given an ASCII code, 
returns the character represented by that code. CHR$(4) returns a 


(CONTROL)-(5). 

CLOSE This command must be issued when you finish using a 
file. It writes all unwritten data to the file, and it releases the fiie 
buffers allocated to that file. 


CREATE This command creates a new file. When used, it places 
a new file of a designated type into a designated directory. 


(CONTROL}-(D) This character must precede every ProDOS 
command used in a program. (CONTROL)-(D) has the ASCII code 4, 
thus it can be generated using the Applesoft function call, 


CHRS(4). 


(CoNTROL)-(RESET) This combination of keystrokes usually causes 
an Applesoft program or command to stop immediately. If a 


program disabies the (CONTROL)-(RESET) feature, you need to turn 
the Apple II off to get the program to stop. 


DASH (-) This command runs a BASIC, machine-language, 
EXEC, or system program. 


DELETE This command removes a file from its directory. A 
deleted file cannot be recovered. 
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directory file (type DIR) A file that contains the names and 
locations on the disk of other files. Related files should be grouped 
together into a single directory file. See also volume directory. 


disk A flat circular piece of plastic or metal. dipped into glue and 
coated with a fine metallic powder, onto which information is 
magnetically recorded. 


disk drive A device that can read information from and record 
information on a disk. ProDOS lets the Apple ۱۱ communicate with 
all disk drives manufactured by Apple Computer, Inc. for the 
Apple II. 


element As defined in this manual, a string of characters, 
terminated by a comma or a carriage return, that can be read 
using the BASIC INPUT statement. For example, INPUT A$,B$ 
reads two elements. 


ENDFILE End of file. When you display a disk’s catalog, the 
column of information labeled EHF ILE tells the number of bytes 
that each file would occupy if all the disk space allocated to that 
file were filled. Refer to Chapter 3 for more details. 


/EXAMPLES The volume name of the disk that contains the 
ProDOS program and the examples for this manual. This disk 
contains the version of the system file that must be on every 
ProDOS startup disk. 


EXEC This command causes input to be taken from a sequential 
text file rather than from the keyboard. When you use EXEC, you 

control the operation of the Apple ۱۱ by using commands that are 

stored in a text file. 


field Ina file, a string of characters preceded by a carriage return 
character, and terminated by a carriage return character. A field is 
written to a file by each PRINT statement not terminated by a 
semicolon. The INPUT command reads an entire field from a file. 


file A file is a named, ordered collection of information on a disk. 
When you use ProDOS to place information on a disk, you give the 
file a name and a type. The file's type determines how information 
is encoded in that file. 


filename The name that identifies a file. A ProDOS filename has 
a maximum of 15 characters. It can contain letters, digits, and 
periods, but it must begin with a letter. 


FLUSH Send unwritten data to its file. Use this command to 
ensure that the data in a file is identical to the data written to the 
file. FLUSH is like CLOSE, except the file remains open. 
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format To prepare the magnetic surface of a disk for the storage 
of information. The ProDOS Filer lets you format all types of disks. 
This utility replaces the DOS command INIT, which was used to 
format Disk Il disks. 


FRE This command is used to access the ProDOS fast 
housekeeping routines. 


HELPSCREENS A file, stored on the /EXAMPLES disk, that 
contains اله‎ the help screens. Each screen is stored in a single 
512-byte record of a random-access text file. For the HELP 
command to be usable, this file must be on the disk from which 
ProDOS was started up, and the command - HELF must have 
been previously issued. 


hexadecimal Encoded using the base-16 numbering system. 
Hexadecimal numbers are formed using the ten digits 0 through 9 
and the six capital letters A through F. All hexadecimal numbers 
used with ProDOS must be preceded by the symbol $ ۰ 


IN# This command designates the source of subsequent input 
characters. It can be used to designate a device in a slot or a 
machine-language routine as the source of input. 


input routine A machine-language routine that performs the 
reading of characters. The standard input routine reads 
characters from the keyboard. A different input routine might, for 
example, read them from an external terminal. 


language card An Apple li interface card that. when placed in 
slot 0 of a 48K Apple Il, gives the Apple Il access to a total of 

64K of memory. If you have an Apple ۱۱ or Apple ۱۱ Plus, you need a 
language card, or the equivalent, to use ProDOS. 


LOAD This command brings a BASIC program into memory from 
a file. it clears the current BASIC program and variables from 
memory and brings in the new program. 


load address The first address in memory from which data was 
BSAVEd into a file. When that file is BLOADed or BRUN, it is 
placed in memory starting at the load address unless you specify 
otherwise. The load address of a binary file is listed in the column 
labeled ziig ٣٣۴٣ when you display a catalog of files. 


LOCK This command protects a file from being accidentally 
renamed, deleted, or altered. 


machine-language interface (MLI) The set of machine- 
language routines, stored in the file named PRODOS, with which 
ProDOS talks to disk drives. The ProDOS Technical Reference 
Manual contains a full explanation of the ProDOS machine- 
language interface. 
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NAME When a Catalog of files is displayed on the screen, the 
HAME column contains the names of the files in the listed 
directory. 


OPEN This command allocates space in memory for a file’s 
buffers, and it sets the file position pointer to the beginning of the 
file. The next file-related command to be issued must be a READ 
or a WRITE. All files opened must be ciosed. 


option An item in the syntax of a ProDOS command that 
determines a singie aspect of the command's action, such as a 
pathname or a file type. Unbracketed options must be included 
each time the command is used, bracketed options can be 
specified as needed, and two options separated by a vertical line 
are alternates. 


output routine A machine-language routine that performs the 
sending of characters. The standard output routine writes 
characters to the screen. A different output routine might, for 
example, send them to a printer. 


partial pathname A portion of a pathname. A partial pathname 
does not begin with a slash, and it does not have to (but may) 
begin with the name of a volume directory. When you use a partial 
pathname in a command, the prefix is usually attached to the front 
to form a full pathname. A partial pathname can be no more than 
64 characters long. 


pathname A series of filenames, preceded and separated by 
slashes, that indicates the entire path, from volume directory to 
file, that ProDOS must foliow to find that file. A pathname used in a 
command can contain no more than 64 characters, slashes 
included. (The pathname formed by the prefix and a partial 
pathname can be up to 128 characters long.) 


POSITION This command causes a specified number of fields to 
be read and discarded from an open fiie. It is used to move the 
position of the file pointer forward in the file. 


PR# This command sends output to a slot or to a machine- 
language program. It specifies an output routine in the ROM on à 
peripheral card or in a machine-language routine in RAM by 
changing the address of the standard output routine used by the 
Apple Il. 


prefix A pathname set to indicate a specific directory file. When 
you use a partial pathname, the prefix is added to the front of it. 
You set the value of the prefix using the PREFIX command. A 
prefix can be no more than 64 characters long, including siashes. 
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ProDOS command Any one of the 28 commands recognized by 
ProDOS. Each has its own syntax, all can be used within 
programs, and all but five (text file commands) can be used from 
immediate mode. ProDOS commands used from within programs 
must be issued as part of a PRINTed string, and must be preceded 


by (CONTROL)-(5). 


/RAM The volume name of a small volume automatically placed 
by ProDOS in the alternate 64K of an Apple lle with an Extended 
80-Column Text Card. It can be used just like a disk volume; 
however, the information stored on it disappears when the 
computer is turned off. 


Random Access Memory (RAM) This is the readable and 
writable memory of the Apple Il. Its contents are usually filled with 
programs from a disk, and they are lost when the Apple ll is turned 
off. An Apple ۱۱ must have 64K of RAM to use ProDOS. 


random-access text file A text file that is partitioned into an 
unlimited number of uniform-length compartments called records. 
When you open a random-access text file for the first time you 
must specify its record length. No record is placed in the file until 
written to. Each record can be individually read from or written to, 
hence the name, random-access. 


READ This command, when used after the OPEN command, 
prepares a file to be read. It can also select the position in the file 
(record, field, and byte) of the next piece of information to be read. 
Until the next ProDOS command is issued, subsequent INPUT 
statements are satisfied by data from the file. 


Read Only Memory (ROM) In the context of this manual, ROM 
refers to semiconductor chips in the Apple Il or on peripheral 
cards that contain programs essential to the system's operation. 
The contents of ROM are permanent and unalterable. The Apple | 
comes with ROM chips that contain the system Monitor and a 
version of BASIC, and the ROM on a disk controller card contains 
programs that let the Apple ۱۱ communicate with one or two disk 
drives. 


record A unit of storage in a random-access text file. Every 
random-access text file can contain a very large number of 
records; each record holds the exact same number of characters. 
A program specifies a file's record length (in bytes) when the file is 
first opened; it must subsequently read and write data into specific 
records within the file. 


record length The length of a random-access text file's records 
in bytes. The maximum record length is 65535 bytes; the minimum 
is 1. 
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RENAME This command allows you to change the name of a file. j 
You cannot use this command to move the file trom one directory 

to another, only to change its name within a directory. A file must 

be uniocked to be renamed. 


RESTORE This command ciears the BASIC variables currently in 
memory, and it reads in a new set of variables from a variable file 
(type VAR). See also STORE. 


RUN This command clears the current BASIC program and 
variables from memory, brings a BASIC program into memory 
from a file, and runs it. An option lets you specify the first program 
line to be run. 


-wame € 
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SAVE This command lets you save the BASIC program currently a 
3 in memory as a BASIC program file (type BAS). 


sequential-access text file A text file made up of a sequence of 

fields. A field is a string of characters terminated by a carriage 

return character, Sequential text files are best used for types of 

data that will be stored and retrieved sequentially. 0 


startup To get the system running. tn the context of ProDOS, 
starting up is the process of reading the ProDOS program (in the 
files PRODOS and BASIC.SYSTEM) from the disk, and running it. 


startup disk A disk that contains all the information needed to 
3 get the computer running. A ProDOS startup disk must be 
formatted using the ProDOS Filer, and it must contain the files 
PRODOS and BASIC.SYSTEM. 


STORE This command causes the BASIC variables currently in 
memory to be arranged in a compact form and then placed in a 
BASIC variable file (type VAR). The variables so stored can be 
returned to memory using the RESTORE command. 
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SUBTYPE in a catalog, the column labeled 557 FFE contains 
two types of information: for a random-access text file, the file's 
record length (R) in decimal; and for a binary file, the file's load 
address (L) in hexadecimal. 


syntax A representation of a command that specifies all the 
possible forms the command can take. The syntax of each 
ProDOS command is given as a command word followed by a list 
of options. 


SYSTEM A file with a name of the form XXX.SYSTEM must be in 
the volume directory of every startup disk; it contains the system 
program that is run when the disk is started up. On the 
/EXAMPLES disk, BASIC.SYSTEM contains the ProDOS BASIC 
program; on the disk named /USERS.DISK, FILER.SYSTEM 
contains the ProDOS Filer. 
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text file (type TXT) A file whose contents are interpreted as 
characters encoded using the ASCII format. ProDOS defines two 
types of text files: sequential, a grouping of sequentially accessible 
fields ot text; and random-access, a collection of equal-sized, and 
independently accessible, groups of characters. 


TYPE In a catalog, the column with this heading names the type 
ot each file listed. Types are given as three-letter abbreviations. 
There is a list of file type abbreviations in Table A-2. 


UNLOCK This command reverses the effect of the LOCK 
command. A file must be unlocked if it is to be renamed, deleted, 
or altered. 


/USERS.DISK The /USERS.DISK disk contains utilities 
programs with which you can format disks, perform ail file 
maintenance (create, rename, delete, copy), and convert files 
between DOS 3.3 format and ProDOS format. These programs are 
explained in the ProDOS User's Manual. 


volume A source or destination of information. As used in this 
manual, volume aiways refers to a disk. It could also, for examp 
refer to a magnetic tape or a location in à network. 


volume directory The main directory of à volume. On a disk, the 
volume directory is a file that contains the names and locations on 
that disk of up to 51 other files, any of which may themselves be 
directory files. ; 


WRITE This command, when used after the OPEN command, 
prepares a file to be written to. Until the next ProDOS command is 
issued, al! subsequent PRINT statements send characters to this 
file. 


write-protected A disk drive that uses flexible disks can only 
write on a disk that has a small notch in the proper location. If this 
notch is covered, or if the notch does not exist, the disk is write- 
protected. The notch itself is referred to as a write-enable notch. 
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